1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
---
title: String.prototype.localeCompare()
slug: Web/JavaScript/Reference/Global_Objects/String/localeCompare
tags:
- Internacionalização
- JavaScript
- Prototipo
- Referencia
- String
- localeCompare()
- metodo
translation_of: Web/JavaScript/Reference/Global_Objects/String/localeCompare
---
<div>{{JSRef}}</div>
<p>O método <code>localeCompare()</code> retorna um número que indica se uma string de referência vem antes ou depois, ou é a mesma que a string fornecida na ordem de classificação.</p>
<div>{{EmbedInteractiveExample("pages/js/string-localecompare.html")}}</div>
<p>Os novos argumentos <em><code>locales</code></em> e <em><code>options</code></em> permitem que os aplicativos especifiquem o idioma cuja ordem da ordenação deve ser usada e personalizem o comportamento da função. Em implementações mais antigas, que ignoram os argumentos <em><code>locales</code></em> e <em><code>options</code></em>, a localidade e a ordem de classificação usadas são totalmente dependentes da implementação.</p>
<h2 id="Sintaxe">Sintaxe</h2>
<pre class="syntaxbox notranslate"><code><var>referenceStr</var>.localeCompare(<var>compareString</var>[, <var>locales</var>[, <var>options</var>]])</code></pre>
<h3 id="Parâmetros">Parâmetros</h3>
<dl>
<dt><code><var>compareString</var></code></dt>
<dd>A string com a qual a <em><code>referenceStr</code></em> é comparada.</dd>
<dt><code><var>locales</var></code> <var>e </var><code><var>options</var></code></dt>
<dd>
<p>Esses argumentos personalizam o comportamento da função e permitem que os aplicativos especifiquem o idioma cujas convenções de formatação devem ser usadas. Em implementações que ignoram os argumentos <em><code>locales</code></em> e <em><code>options</code></em>, a localidade usada e a forma da string retornada são inteiramente dependentes da implementação.</p>
<p>Consulte o <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator">construtor </a><code><a href="https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator">Intl.Collator()</a></code> para obter detalhes sobre esses parâmetros e como usá-los.</p>
</dd>
</dl>
<h3 id="Valor_retornado">Valor retornado</h3>
<p>Um número <strong>negativo</strong> se <em><code>referenceStr</code></em> ocorrer antes de <em><code>compareString</code></em>. Um número <strong>positivo</strong> se o <em><code>referenceStr</code></em> ocorrer após <em><code>compareString</code></em>. <code>0</code> se eles forem equivalentes.</p>
<h2 id="Descrição">Descrição</h2>
<p>Retorna um inteiro indicando se <em><code>referenceStr</code></em> vem antes, depois ou é equivalente a <em><code>compareString</code></em>.</p>
<ul>
<li>Negativo quando o <em><code>referenceStr</code></em> ocorre antes de <em><code>compareString</code></em></li>
<li>Positivo quando o <em><code>referenceStr</code></em> ocorre após <em><code>compareString</code></em></li>
<li>Retorna <code>0</code> se eles forem equivalentes</li>
</ul>
<div class="blockIndicator warning">
<p><strong>NÃO confie em valores de retorno exatos de -1 ou 1!</strong></p>
<p>Os resultados de números inteiros negativos e positivos variam entre os navegadores (bem como entre as versões dos navegadores) porque a especificação W3C exige apenas valores negativos e positivos. Alguns navegadores podem retornar <code>-2</code> ou <code>2</code>, ou mesmo algum outro valor negativo ou positivo.</p>
</div>
<h2 id="Performance">Performance</h2>
<p>Ao comparar um grande número de strings, como na classificação de grandes arrays, é melhor criar um objeto {{jsxref("Global_Objects/Collator", "Intl.Collator")}} e usar a função fornecida por sua propriedade {{jsxref("Collator.prototype.compare", "compare")}}.</p>
<h2 id="Exemplos">Exemplos</h2>
<h3 id="Usando_localeCompare">Usando <code>localeCompare()</code></h3>
<pre class="brush: js notranslate">// A letra "a" está antes de "c" produzindo um valor negativo
'a'.localeCompare('c'); // -2 ou -1 (ou algum outro valor negativo)
// Alfabeticamente, a palavra "verificar" vem depois de "contra", produzindo um valor positivo
'verificar'.localeCompare('contra'); // 2 ou 1 (ou algum outro valor negativo)
// "a" e "a" são equivalentes, resultando em um valor neutro de zero
'a'.localeCompare('a'); // 0
</pre>
<h3 id="Ordenar_um_array">Ordenar um array</h3>
<p><code>localeCompare()</code> permite a ordenação sem distinção entre maiúsculas e minúsculas em um array.</p>
<pre class="brush: js notranslate">let items = ['réservé', 'Premier', 'Cliché', 'communiqué', 'café', 'Adieu'];
items.sort( (a, b) => a.localeCompare(b, 'fr', {ignorePunctuation: true}));
// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé']
</pre>
<h3 id="Verifique_o_suporte_do_navegador_para_os_novos_argumentos">Verifique o suporte do navegador para os novos argumentos</h3>
<p>Os argumentos <em><code>locales</code></em> e <em><code>options</code></em> ainda não são suportados em todos os navegadores.</p>
<p>Para verificar se uma implementação os suporta, use o argumento <code>"i"</code> (um requisito de rejeição das tags de linguagem ilegal) e procure uma exceção {{jsxref ("RangeError")}}:</p>
<pre class="brush: js notranslate">function localeCompareSupportsLocales() {
try {
'foo'.localeCompare('bar', 'i');
} catch (e) {
return e.name === 'RangeError';
}
return false;
}
</pre>
<h3 id="Usando_locales">Usando <code>locales</code></h3>
<p>Os resultados fornecidos por <code>localeCompare()</code> variam entre os idiomas. Para obter a ordem de classificação do idioma usado na interface do usuário de seu aplicativo, certifique-se de especificar esse idioma (e possivelmente alguns idiomas substitutos) usando o argumento <em><code>locales</code></em>:</p>
<pre class="brush: js notranslate">console.log('ä'.localeCompare('z', 'de')); // um valor negativo: em alemão, ä é classificado antes de z
console.log('ä'.localeCompare('z', 'sv')); // um valor positivo: em sueco, ä é classificado após z
</pre>
<h3 id="Usando_options">Usando <code>options</code></h3>
<p>Os resultados fornecidos por <code>localeCompare()</code> podem ser personalizados usando o argumento <em><code>options</code></em>:</p>
<pre class="brush: js notranslate">// em alemão, ä tem a como letra base
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0
// em sueco, ä e a são letras de base separadas
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // um valor positivo
</pre>
<h3 id="Ordenação_numérica">Ordenação numérica</h3>
<pre class="brush: js notranslate">// por padrão, "2" > "10"
console.log(<span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body">"2".localeCompare("10")</span></span></span>); // 1
// numeric using options:
console.log(<span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body">"2".localeCompare("10", undefined, {numeric: true})</span></span></span>); // -1
// numeric using locales tag:
console.log(<span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body">"2".localeCompare("10", "en-u-kn-true")</span></span></span>); // -1
</pre>
<h2 id="Especificações">Especificações</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Especificação</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName('ESDraft', '#sec-string.prototype.localecompare', 'String.prototype.localeCompare')}}</td>
</tr>
<tr>
<td>{{SpecName('ES Int Draft', '#sup-String.prototype.localeCompare', 'String.prototype.localeCompare')}}</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Compatibilidade com navegadores</h2>
<p>{{Compat("javascript.builtins.String.localeCompare")}}</p>
<h2 id="Veja_também">Veja também</h2>
<ul>
<li>{{jsxref("Global_Objects/Collator", "Intl.Collator")}}</li>
</ul>
|
