Translate array constructor

raulbrito · raulbrito · commit 04142c1eccb5 · 2011-11-06T19:59:42.000+01:00
diff --git a/doc/pt/constructor.md b/doc/pt/constructor.md
@@ -0,0 +1,34 @@
+## O  constructor do `Array`
+
+Visto que o constructor do `Array` &eacute; amb&iacute;guo na forma como age com os seus par&acirc;metros,
+&eacute; altamente recomendado utilizar a nota&ccedil;&atilde;o literal do Array - `[]` - 
+na cria&ccedil;&atilde;o de novos vectores.
+
+    [1, 2, 3]; // Resultado: [1, 2, 3]
+    new Array(1, 2, 3); // Resultado: [1, 2, 3]
+
+    [3]; // Resultado: [3]
+    new Array(3); // Resultado: []
+    new Array('3') // Resultado: ['3']
+
+No caso de haver s&oacute; um par&acirc;metro passado ao constructor do `Array`, e
+esse argumento ser um `Number`, o constructor retorna um novo
+vector *espar&ccedil;o* com a propriedade `length` com o valor do argumento.
+Al&eacute;m disso, *s&oacute;* a propriedade `length` do novo vector &eacute; definida desta
+maneira; os indices do vector n&atilde;o s&atilde;o inicializados.
+
+    var arr = new Array(3);
+    arr[1]; // indefinido
+    1 in arr; // falso, o &iacute;ndice nao foi definido
+
+O facto de ser possivel definir o tamanho do vector inicialmente s&oacute;
+&eacute; util nalguns casos, tal como na repeti&ccedil;&atilde;o de um objecto de tipo
+`String&acute;, visto que evita a utiliza&ccedil;&atilde;o de um ciclo `for`.
+
+    new Array(count + 1).join(stringToRepeat);
+
+### Em conclus&atilde;o
+
+O uso do constructor do `Array` deve ser evitado tanto como possivel. Os
+literais s&atilde;o definitivamente preferidos. Sao mais curtos e tem uma
+sintaxe mais clara; o que aumenta a legibilidade do c&oacute;digo.
diff --git a/doc/pt/general.md b/doc/pt/general.md
@@ -0,0 +1,58 @@
+## Array Iteration and Properties
+
+Although arrays in JavaScript are objects, there are no good reasons to use
+the [`for in loop`](#object.forinloop) in for iteration on them. In fact, there 
+are a number of good reasons **against** the use of `for in` on arrays.
+
+> **Note:** JavaScript arrays are **not** *associative arrays*. JavaScript only 
+> has [objects](#object.general) for mapping keys to values. And while associative 
+> arrays **preserve** order, objects **do not**.
+
+Because the `for in` loop enumerates all the properties that are on the prototype 
+chain and because the only way to exclude those properties is to use 
+[`hasOwnProperty`](#object.hasownproperty), it is already up to **twenty times** 
+slower than a normal `for` loop.
+
+### Iteration
+
+In order to achieve the best performance when iterating over arrays, it is best
+to use the classic `for` loop.
+
+    var list = [1, 2, 3, 4, 5, ...... 100000000];
+    for(var i = 0, l = list.length; i < l; i++) {
+        console.log(list[i]);
+    }
+
+There is one extra catch in the above example, which is the caching of the 
+length of the array via `l = list.length`.
+
+Although the `length` property is defined on the array itself, there is still an
+overhead for doing the lookup on each iteration of the loop. And while recent 
+JavaScript engines **may** apply optimization in this case, there is no way of
+telling whether the code will run on one of these newer engines or not. 
+
+In fact, leaving out the caching may result in the loop being only **half as
+fast** as with the cached length.
+
+### The `length` Property
+
+While the *getter* of the `length` property simply returns the number of
+elements that are contained in the array, the *setter* can be used to 
+**truncate** the array.
+
+    var foo = [1, 2, 3, 4, 5, 6];
+    foo.length = 3;
+    foo; // [1, 2, 3]
+
+    foo.length = 6;
+    foo; // [1, 2, 3]
+
+Assigning a smaller length does truncate the array, but increasing the length 
+does not have any effect on the array.
+
+### In Conclusion
+
+For the best performance, it is recommended to always use the plain `for` loop
+and cache the `length` property. The use of `for in` on an array is a sign of
+badly written code that is prone to bugs and bad performance. 
+

-Original file line number
+Diff line change
@@ @@ -0,0 +1,34 @@ @@
 +## O  constructor do `Array`
++
 +Visto que o constructor do `Array` é ambíguo na forma como age com os seus parâmetros,
 +é altamente recomendado utilizar a notação literal do Array - `[]` -
 +na criação de novos vectores.
++
 +    [1, 2, 3]; // Resultado: [1, 2, 3]
 +    new Array(1, 2, 3); // Resultado: [1, 2, 3]
++
 +    [3]; // Resultado: [3]
 +    new Array(3); // Resultado: []
 +    new Array('3') // Resultado: ['3']
++
 +No caso de haver só um parâmetro passado ao constructor do `Array`, e
 +esse argumento ser um `Number`, o constructor retorna um novo
 +vector *esparço* com a propriedade `length` com o valor do argumento.
 +Além disso, *só* a propriedade `length` do novo vector é definida desta
 +maneira; os indices do vector não são inicializados.
++
 +    var arr = new Array(3);
 +    arr[1]; // indefinido
 +    1 in arr; // falso, o índice nao foi definido
++
 +O facto de ser possivel definir o tamanho do vector inicialmente só
 +é util nalguns casos, tal como na repetição de um objecto de tipo
 +`String´, visto que evita a utilização de um ciclo `for`.
++
 +    new Array(count + 1).join(stringToRepeat);
++
 +### Em conclusão
++
 +O uso do constructor do `Array` deve ser evitado tanto como possivel. Os
 +literais são definitivamente preferidos. Sao mais curtos e tem uma
 +sintaxe mais clara; o que aumenta a legibilidade do código.