merging all conflicts

Author: iliakan

1-js/01-getting-started/1-intro/article.md

@@ -1,6 +1,10 @@
 # Uma Introdução ao JavaScript
 
+<<<<<<< HEAD
 Vamos ver o que há de tão especial no JavaScript, o que podemos fazer com ele, e que outras tecnologias funcionam bem com ele.
+=======
+Let's see what's so special about JavaScript, what we can achieve with it, and what other technologies play well with it.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 ## O que é JavaScript?
 
@@ -67,8 +71,13 @@ Exemplos de tais restrições incluem:
 
     Os navegadores modernos permitem que ele trabalhe com arquivos, mas o acesso é limitado e fornecido apenas se o usuário executar determinadas ações, como "dropping" de um arquivo em uma janela do navegador ou selecioná-lo por meio de uma tag `<input>`.
 
+<<<<<<< HEAD
    Existem maneiras de interagir com a câmera / microfone e outros dispositivos, mas eles exigem permissão explícita do usuário. Assim, uma página habilitada para JavaScript pode não habilmente habilitar uma câmera web, observar os arredores e enviar as informações para a [NSA](https://pt.wikipedia.org/wiki/Ag%C3%AAncia_de_Seguran%C3%A7a_Nacional).
 - Diferentes abas/janelas geralmente não se conhecem mutuamente. Às vezes sim, por exemplo, quando uma janela usa JavaScript para abrir a outra. Mas mesmo neste caso, JavaScript de uma página pode não acessar a outra se eles vierem de sites diferentes (de um domínio, protocolo ou porta diferente).
+=======
+    There are ways to interact with camera/microphone and other devices, but they require a user's explicit permission. So a JavaScript-enabled page may not sneakily enable a web-camera, observe the surroundings and send the information to the [NSA](https://en.wikipedia.org/wiki/National_Security_Agency).
+- Different tabs/windows generally do not know about each other. Sometimes they do; for example when one window uses JavaScript to open the other one. But even in this case, JavaScript from one page may not access the other if they come from different sites (from a different domain, protocol or port).
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
     Isso é chamado de "Política de mesma origem ". Para contornar isso, *ambas as páginas* devem conter um código JavaScript especial que lida com a troca de dados.
 
@@ -116,6 +125,12 @@ Há mais. Claro que, mesmo que usemos uma dessas linguagens transpiladas, també
 
 ## Resumo
 
+<<<<<<< HEAD
 - O JavaScript foi inicialmente criado como uma linguagem somente de navegador, mas agora é usado em muitos outros ambientes também.
 - Hoje, o JavaScript tem uma posição única como a linguagem de navegador mais amplamente adotada, com integração total com HTML/CSS.
 - Existem muitas linguagens que são "transpiladas" para JavaScript e que oferecem certas funcionalidades. Recomenda-se dar uma olhada nelas, pelo menos brevemente, depois de dominar o JavaScript.
+=======
+- JavaScript was initially created as a browser-only language, but it is now used in many other environments as well.
+- Today, JavaScript has a unique position as the most widely-adopted browser language with full integration in HTML/CSS.
+- There are many languages that get "transpiled" to JavaScript and provide certain features. It is recommended to take a look at them, at least briefly, after mastering JavaScript.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779

1-js/02-first-steps/18-javascript-specials/article.md

@@ -144,7 +144,7 @@ Assignments
 : There is a simple assignment: `a = b` and combined ones like `a *= 2`.
 
 Bitwise
-: Bitwise operators work with 32-bit integers at the lowest, bit-level: see the [docs](mdn:/JavaScript/Reference/Operators/Bitwise_Operators) when they are needed.
+: Bitwise operators work with 32-bit integers at the lowest, bit-level: see the [docs](mdn:/JavaScript/Guide/Expressions_and_Operators#Bitwise) when they are needed.
 
 Conditional
 : The only operator with three parameters: `cond ? resultA : resultB`. If `cond` is truthy, returns `resultA`, otherwise `resultB`.

1-js/04-object-basics/01-object/8-multiply-numeric/task.md

@@ -2,9 +2,15 @@ importância: 3
 
 ---
 
+<<<<<<< HEAD
 # Multiplica as propriedades numéricas por 2
 
 Crie uma função `multiplyNumeric(obj)` que multiplique todas as propriedades numéricas de `obj` por `2`.
+=======
+# Multiply numeric property values by 2
+
+Create a function `multiplyNumeric(obj)` that multiplies all numeric property values of `obj` by `2`.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 Por exemplo:
 

1-js/04-object-basics/02-object-copy/article.md

@@ -1,10 +1,12 @@
-# Object copying, references
+# Object references and copying
 
-One of the fundamental differences of objects vs primitives is that they are stored and copied "by reference".
+One of the fundamental differences of objects versus primitives is that objects are stored and copied "by reference", as opposed to primitive values: strings, numbers, booleans, etc -- that are always copied "as a whole value".
 
-Primitive values: strings, numbers, booleans -- are assigned/copied "as a whole value".
+That's easy to understand if we look a bit "under a cover" of what happens when we copy a value.
 
-For instance:
+Let's start with a primitive, such as a string.
+
+Here we put a copy of `message` into `phrase`:
 
 ```js
 let message = "Hello!";
@@ -15,21 +17,31 @@ As a result we have two independent variables, each one is storing the string `"
 
 ![](variable-copy-value.svg)
 
+Quite an obvious result, right?
+
 Objects are not like that.
 
-**A variable stores not the object itself, but its "address in memory", in other words "a reference" to it.**
+**A variable assigned to an object stores not the object itself, but its "address in memory", in other words "a reference" to it.**
 
-Here's the picture for the object:
+Let's look at an example of such variable:
 
 ```js
 let user = {
   name: "John"
 };
 ```
 
+And here's how it's actually stored in memory:
+
 ![](variable-contains-reference.svg)
 
-Here, the object is stored somewhere in memory. And the variable `user` has a "reference" to it.
+The object is stored somewhere in memory (at the right of the picture), while the `user` variable (at the left) has a "reference" to it.
+
+We may think of an object variable, such as `user`, as of a sheet of paper with the address.
+
+When we perform actions with the object, e.g. take a property `user.name`, JavaScript engine looks into that address and performs the operation on the actual object.
+
+Now here's why it's important.
 
 **When an object variable is copied -- the reference is copied, the object is not duplicated.**
 
@@ -45,6 +57,8 @@ Now we have two variables, each one with the reference to the same object:
 
 ![](variable-copy-reference.svg)
 
+As you can see, there's still one object, now with two variables that reference it.
+
 We can use any variable to access the object and modify its contents:
 
 ```js run
@@ -59,15 +73,14 @@ admin.name = 'Pete'; // changed by the "admin" reference
 alert(*!*user.name*/!*); // 'Pete', changes are seen from the "user" reference
 ```
 
-The example above demonstrates that there is only one object. As if we had a cabinet with two keys and used one of them (`admin`) to get into it. Then, if we later use another key (`user`) we can see changes.
 
-## Comparison by reference
+It's just as if we had a cabinet with two keys and used one of them (`admin`) to get into it. Then, if we later use another key (`user`) we can see changes.
 
-The equality `==` and strict equality `===` operators for objects work exactly the same.
+## Comparison by reference
 
-**Two objects are equal only if they are the same object.**
+Two objects are equal only if they are the same object.
 
-Here two variables reference the same object, thus they are equal:
+For instance, here `a` and `b` reference the same object, thus they are equal:
 
 ```js run
 let a = {};
@@ -77,7 +90,7 @@ alert( a == b ); // true, both variables reference the same object
 alert( a === b ); // true
 ```
 
-And here two independent objects are not equal, even though both are empty:
+And here two independent objects are not equal, even though they look alike (both are empty):
 
 ```js run
 let a = {};
@@ -86,7 +99,7 @@ let b = {}; // two independent objects
 alert( a == b ); // false
 ```
 
-For comparisons like `obj1 > obj2` or for a comparison against a primitive `obj == 5`, objects are converted to primitives. We'll study how object conversions work very soon, but to tell the truth, such comparisons occur very rarely, usually as a result of a coding mistake.
+For comparisons like `obj1 > obj2` or for a comparison against a primitive `obj == 5`, objects are converted to primitives. We'll study how object conversions work very soon, but to tell the truth, such comparisons are needed very rarely, usually they appear as a result of a programming mistake.
 
 ## Cloning and merging, Object.assign
 

1-js/04-object-basics/04-object-methods/article.md

@@ -32,11 +32,11 @@ user.sayHi = function() {
 user.sayHi(); // Hello!
 ```
 
-Here we've just used a Function Expression to create the function and assign it to the property `user.sayHi` of the object.
+Here we've just used a Function Expression to create a function and assign it to the property `user.sayHi` of the object.
 
-Then we can call it. The user can now speak!
+Then we can call it as `user.sayHi()`. The user can now speak!
 
-A function that is the property of an object is called its *method*.
+A function that is a property of an object is called its *method*.
 
 So, here we've got a method `sayHi` of the object `user`.
 
@@ -163,18 +163,24 @@ let user = {
 let admin = user;
 user = null; // overwrite to make things obvious
 
-admin.sayHi(); // Whoops! inside sayHi(), the old name is used! error!
+*!*
+admin.sayHi(); // TypeError: Cannot read property 'name' of null
+*/!*
 ```
 
 If we used `this.name` instead of `user.name` inside the `alert`, then the code would work.
 
 ## "this" is not bound
 
+<<<<<<< HEAD
 <<<<<<< HEAD
 In JavaScript, "this" keyword behaves unlike most other programming languages. First, it can be used in any function.
 =======
 In JavaScript, keyword `this` behaves unlike most other programming languages. It can be used in any function.
 >>>>>>> e074a5f825a3d10b0c1e5e82561162f75516d7e3
+=======
+In JavaScript, keyword `this` behaves unlike most other programming languages. It can be used in any function, even if it's not a method of an object.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 There's no syntax error in the following example:
 

1-js/04-object-basics/07-optional-chaining/article.md

@@ -3,21 +3,25 @@
 
 [recent browser="new"]
 
-The optional chaining `?.` is an error-proof way to access nested object properties, even if an intermediate property doesn't exist.
+The optional chaining `?.` is a safe way to access nested object properties, even if an intermediate property doesn't exist.
 
-## The problem
+## The "non-existing property" problem
 
 If you've just started to read the tutorial and learn JavaScript, maybe the problem hasn't touched you yet, but it's quite common.
 
-For example, some of our users have addresses, but few did not provide them. Then we can't safely read `user.address.street`:
+As an example, let's consider objects for user data. Most of our users have addresses in `user.address` property, with the street `user.address.street`, but some did not provide them. 
+
+In such case, when we attempt to get `user.address.street`, we'll get an error:
 
 ```js run
-let user = {}; // the user happens to be without address
+let user = {}; // the user without "address" property
 
 alert(user.address.street); // Error!
 ```
 
-Or, in the web development, we'd like to get an information about an element on the page, but it may not exist:
+That's the expected result, JavaScript works like this, but many practical cases we'd prefer to get `undefined` instead of an error (meaning "no street").
+
+...And another example. In the web development, we may need to get an information about an element on the page, that sometimes doesn't exist:
 
 ```js run
 // Error if the result of querySelector(...) is null
@@ -34,7 +38,7 @@ let user = {}; // user has no address
 alert( user && user.address && user.address.street ); // undefined (no error)
 ```
 
-AND'ing the whole path to the property ensures that all components exist, but is cumbersome to write.
+AND'ing the whole path to the property ensures that all components exist (if not, the evaluation stops), but is cumbersome to write.
 
 ## Optional chaining
 
@@ -86,7 +90,7 @@ We should use `?.` only where it's ok that something doesn't exist.
 
 For example, if according to our coding logic `user` object must be there, but `address` is optional, then `user.address?.street` would be better.
 
-So, if `user` happens to be undefined due to a mistake, we'll know about it and fix it. Otherwise, coding errors can be silenced where not appropriate, and become more difficult to debug.
+So, if `user` happens to be undefined due to a mistake, we'll see a programming error about it and fix it. Otherwise, coding errors can be silenced where not appropriate, and become more difficult to debug.
 ```
 
 <<<<<<< HEAD
@@ -102,28 +106,34 @@ If there's no variable `user` at all, then `user?.anything` triggers an error:
 user?.address;
 ```
 <<<<<<< HEAD
+<<<<<<< HEAD
 The optional chaining only tests for `null/undefined`, doesn't interfere with any other language mechanics.
 =======
 There must be `let/const/var user`. The optional chaining works only for declared variables.
 >>>>>>> e074a5f825a3d10b0c1e5e82561162f75516d7e3
+=======
+There must be a declaration (e.g. `let/const/var user`). The optional chaining works only for declared variables.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 ````
 
 ## Short-circuiting
 
 As it was said before, the `?.` immediately stops ("short-circuits") the evaluation if the left part doesn't exist.
 
-So, if there are any further function calls or side effects, they don't occur:
+So, if there are any further function calls or side effects, they don't occur.
+
+For instance:
 
 ```js run
 let user = null;
 let x = 0;
 
-user?.sayHi(x++); // nothing happens
+user?.sayHi(x++); // no "sayHi", so the execution doesn't reach x++
 
 alert(x); // 0, value not incremented
 ```
 
-## Other cases: ?.(), ?.[]
+## Other variants: ?.(), ?.[]
 
 The optional chaining `?.` is not an operator, but a special syntax construct, that also works with functions and square brackets.
 
@@ -146,13 +156,17 @@ user2.admin?.();
 */!*
 ```
 
-Here, in both lines we first use the dot `.` to get `admin` property, because the user object must exist, so it's safe read from it.
+Here, in both lines we first use the dot (`user1.admin`) to get `admin` property, because the user object must exist, so it's safe read from it.
 
+<<<<<<< HEAD
 <<<<<<< HEAD
 Then `?.()` checks the left part: if the user exists, then it runs (for `user1`). Otherwise (for `user2`) the evaluation stops without errors.
 =======
 Then `?.()` checks the left part: if the admin function exists, then it runs (for `user1`). Otherwise (for `user2`) the evaluation stops without errors.
 >>>>>>> e074a5f825a3d10b0c1e5e82561162f75516d7e3
+=======
+Then `?.()` checks the left part: if the admin function exists, then it runs (that's so for `user1`). Otherwise (for `user2`) the evaluation stops without errors.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 The `?.[]` syntax also works, if we'd like to use brackets `[]` to access properties instead of dot `.`. Similar to previous cases, it allows to safely read a property from an object that may not exist.
 
@@ -177,28 +191,30 @@ Also we can use `?.` with `delete`:
 delete user?.name; // delete user.name if user exists
 ```
 
-```warn header="We can use `?.` for safe reading and deleting, but not writing"
-The optional chaining `?.` has no use at the left side of an assignment:
+````warn header="We can use `?.` for safe reading and deleting, but not writing"
+The optional chaining `?.` has no use at the left side of an assignment.
 
+For example:
 ```js run
-// the idea of the code below is to write user.name, if user exists
+let user = null;
 
 user?.name = "John"; // Error, doesn't work
 // because it evaluates to undefined = "John"
 ```
 
+It's just not that smart.
+````
+
 ## Summary
 
-The `?.` syntax has three forms:
+The optional chaining `?.` syntax has three forms:
 
 1. `obj?.prop` -- returns `obj.prop` if `obj` exists, otherwise `undefined`.
 2. `obj?.[prop]` -- returns `obj[prop]` if `obj` exists, otherwise `undefined`.
-3. `obj?.method()` -- calls `obj.method()` if `obj` exists, otherwise returns `undefined`.
+3. `obj.method?.()` -- calls `obj.method()` if `obj.method` exists, otherwise returns `undefined`.
 
 As we can see, all of them are straightforward and simple to use. The `?.` checks the left part for `null/undefined` and allows the evaluation to proceed if it's not so.
 
 A chain of `?.` allows to safely access nested properties.
 
-Still, we should apply `?.` carefully, only where it's ok that the left part doesn't to exist.
-
-So that it won't hide programming errors from us, if they occur.
+Still, we should apply `?.` carefully, only where it's acceptable that the left part doesn't to exist. So that it won't hide programming errors from us, if they occur.

1-js/05-data-types/03-string/article.md

@@ -102,7 +102,11 @@ alert( 'I*!*\'*/!*m the Walrus!' ); // *!*I'm*/!* the Walrus!
 
 As you can see, we have to prepend the inner quote by the backslash `\'`, because otherwise it would indicate the string end.
 
+<<<<<<< HEAD
 Of course, that refers only to the quotes that are same as the enclosing ones. So, as a more elegant solution, we could switch to double quotes or backticks instead:
+=======
+Of course, only the quotes that are the same as the enclosing ones need to be escaped. So, as a more elegant solution, we could switch to double quotes or backticks instead:
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 ```js run
 alert( `I'm the Walrus!` ); // I'm the Walrus!
@@ -305,8 +309,14 @@ if (str.indexOf("Widget") != -1) {
 }
 ```
 
+<<<<<<< HEAD
 ````smart header="The bitwise NOT trick"
 One of the old tricks used here is the [bitwise NOT](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_Operators#Bitwise_NOT) `~` operator. It converts the number to a 32-bit integer (removes the decimal part if exists) and then reverses all bits in its binary representation.
+=======
+#### The bitwise NOT trick
+
+One of the old tricks used here is the [bitwise NOT](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_NOT) `~` operator. It converts the number to a 32-bit integer (removes the decimal part if exists) and then reverses all bits in its binary representation.
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 For 32-bit integers the call `~n` means exactly the same as `-(n+1)` (due to IEEE-754 format).
 
@@ -338,7 +348,14 @@ if (~str.indexOf("Widget")) {
 It is usually not recommended to use language features in a non-obvious way, but this particular trick is widely used in old code, so we should understand it.
 
 Just remember: `if (~str.indexOf(...))` reads as "if found".
+<<<<<<< HEAD
 ````
+=======
+
+To be precise though, as big numbers are truncated to 32 bits by `~` operator, there exist other numbers that give `0`, the smallest is `~4294967295=0`. That makes such check correct only if a string is not that long.
+
+Right now we can see this trick only in the old code, as modern JavaScript provides `.includes` method (see below).
+>>>>>>> 0599d07b3c13ee25f583fc091cead3c17a7e7779
 
 ### includes, startsWith, endsWith
 

1-js/05-data-types/05-array-methods/7-map-objects/solution.md

@@ -25,7 +25,7 @@ alert( usersMapped[0].id ); // 1
 alert( usersMapped[0].fullName ); // John Smith
 ```
 
-Please note that in for the arrow functions we need to use additional brackets. 
+Please note that in the arrow functions we need to use additional brackets. 
 
 We can't write like this:
 ```js