From bcac96f576cd91783ce5a32320274e02aae34add Mon Sep 17 00:00:00 2001 From: Ashleyanna Rivers Date: Thu, 14 May 2026 00:19:42 -0600 Subject: [PATCH] Chapter 2-4 grammatical fixes --- .../guide/Language Basics/chapter2.md | 44 +++++----- .../guide/Language Basics/chapter3.md | 39 ++++----- .../guide/Language Basics/chapter4.md | 80 ++++++++++--------- 3 files changed, 84 insertions(+), 79 deletions(-) diff --git a/docs/angelscript/guide/Language Basics/chapter2.md b/docs/angelscript/guide/Language Basics/chapter2.md index 682869d7..ae0e286e 100644 --- a/docs/angelscript/guide/Language Basics/chapter2.md +++ b/docs/angelscript/guide/Language Basics/chapter2.md @@ -16,14 +16,14 @@ In this chapter you will learn about: - [Switch statement](#switch-statement) - [Variable Scope](#variable-scope) -> Statements, expressions, conditions and the variable scope are the foundation of every program or script. +> Statements, expressions, conditions, and variable scopes are the foundation of every program or script. --- ## Basic statements Your code is like a recipe, and statements are the individual steps. -Statements are a way to tell the script engine what it needs to do, we already used them in previous chapters, such as the assignment or declaration. +Statements are a way to tell the script engine what it needs to do. We've already used them in the previous chapter, during assignment and declaration. ### Expression Statements @@ -35,7 +35,7 @@ Any expression can be placed on a line as a statement. Examples of expressions i - Subtraction **-** operator - subtracts two values from each other, - Many more, such as **+=**, **-=**, **++**, etc. are available. More about them can be found in the [expression reference table](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_expressions.html). -Such statements need to end with the semicolon (`;`): +Such statements must end with a semicolon (`;`): ```cpp b = a + b; @@ -45,7 +45,7 @@ a += b; AngelScript follows a specific instruction of operation order. Function calls are evaluated first bottom to top, then AS sticks to order of operations as specified in the [Operator Precedence](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_operator_precedence.html) reference. -You can force an order of operations by using parenthesis: +You can force an order of operations by using parentheses: ```cpp float a = 1 + 1.0 / 2; // This will return 1,5 @@ -53,14 +53,14 @@ float b = (1 + 1.0) / 2; // This will return 1 ``` > [!TIP] -> Order of how operators are evaluated for standard math operators such as **+**, **-**, **\***, **/**, etc. follow the standard Order of Operations. +> The order in which operators are evaluated for standard math operators such as **+**, **-**, **\***, **/**, etc. follow the standard Order of Operations. > ### TASK 1: -> Given `float a = 4; float b = 5;` Write a program that calculates the number c given by the equation: `c = (a - 2)^2 + (b + 1) / 2`. +> Given `float a = 4; float b = 5;`, write a program that calculates the number `c` given by the equation: `c = (a - 2)^2 + (b + 1) / 2`. ### Comparison Operators -Comparison operators are operators of which expressions evaluate to the `true` or `false` boolean values. An example of a comparison operator is the equals (**==**) operator, which checks if the two values on both sides of such operator are equal. Another type of a condition operator is the greater than operator (**>**), which checks if the value on the left side is greater than the value on the right side. For comparison operator reference please check the [expression reference table](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_expressions.html). +Comparison operators are operators of which expressions evaluate to the `true` or `false` boolean values. An example of a comparison operator is the equals (**==**) operator, which checks if the values on both sides of the operator are equal. Another type of condition operator is the greater than operator (**>**), which checks if the value on the left side is greater than the value on the right side. For comparison operator references, please check the [expression reference table](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_expressions.html). ```cpp int a = 1; @@ -75,25 +75,25 @@ bool result = a == b; // Result now stores the information if a and b were equal Logic operators are a way to combine comparison expressions in order to achieve one result: -- NOT - denoted as `!`, evaluates to true, if value is false and vice versa, -- AND - denoted as `&&`, evaluates to true, if both values are true, -- OR - denoted as `||`, evaluates to true, if even one of the values is true, else false if both are false, +- NOT - denoted as `!`, evaluates to true if value is false, and vice versa, +- AND - denoted as `&&`, evaluates to true if both values are true, +- OR - denoted as `||`, evaluates to true, even if only one of the values is true, else false if both are false, - XOR - denoted as `^^`, evaluates to true, if and only if **one** of the values is true. ```cpp a && b; // AND -a && b || c; // A combination of AND and OR, a AND b is going to get evaluated first -a && (b || c); // You can use parenthesis to specify which operator should get evaluated first, here OR will get evaluated first +a && b || c; // A combination of AND and OR, a AND b will be evaluated first +a && (b || c); // You can use parentheses to specify which operator should be evaluated first - here OR will get evaluated first ``` > [!NOTE] -> Although AngelScript supports Python-like logic operator notation (and, or, ...) it is recommended to stick to the C-like notation. This is mainly because AS is much more similar to C in it's syntax, and also not every extension adding AS support for your IDE has support for the Python-like notation. +> Although AngelScript supports Python-like logic operator notation (and, or, ...) it is recommended to stick to the C-like notation. This is mainly because AS is much more similar to C in its syntax, and also not every extension adding AS support for your IDE will support Python-like notation. --- ## Conditions -Conditions are a way to tell the engine to execute specific code only if a specific condition is met. For example, only add numbers if they are positive. +Conditions are a way to tell the engine to execute specific code only if a specific condition is met. For example, only adding numbers if they are positive. They should contain an expression that evaluates to true or false, and they can be any sort of valid combination of comparison operators and logic operators, etc. ### If/else Block @@ -113,11 +113,11 @@ if ( a > 10 ) { // Condition 1 ``` > ### TASK 2: -> Given two numerical values *a* and *b* (defined statically in your script) prints out an absolute value of their difference. +> Given two numerical values *a* and *b* (defined statically in your script), print out an absolute value of their difference. ### Switch Statement -The switch statement is a very useful tool for situations where you need to compare to a lot of different cases. It performs the *is equal* operation comparing a value to every value specified in case blocks. It is also much faster than a block of the `if`/`else if`/`else` statements. +The switch statement is a very useful tool for situations where you need to compare a lot of different cases. It performs the *is equal* operation comparing a value to every value specified in case blocks. It is also much faster than a block of the `if`/`else if`/`else` statements. ```cpp switch ( value ) { @@ -136,7 +136,7 @@ switch ( value ) { ``` > [!CAUTION] -> Each case requires a `break` statement after finishing code execution. This is because switch behaves more like the `goto` (C++) functionality, meaning that it doesn't stop executing code after finishing a specific case. The `break` statement will tell the code to go out of the `switch` block. This is also why in the upper example `case 2:` and `case 3:` can be used to both execute the same lines of code. +> Each case requires a `break` statement after finishing code execution. This is because `switch` behaves more like the `goto` (C++) functionality, meaning that it doesn't stop executing code after finishing a specific case. The `break` statement will tell the code to leave the `switch` block. This is also why, in the upper example, `case 2:` and `case 3:` can be used to both execute the same lines of code. > ### TASK 3: > @@ -151,8 +151,8 @@ switch ( value ) { ## Variable Scope -Variable Scope determines which data can be accessed from where. In AngelScript the Variable Scope behaves exactly as the one in C++. -In general the Variable Scope makes programs use less memory by not holding expired (not useful anymore) information inside the memory, as an example: +**Variable scope** determines which data can be accessed from where. In AngelScript, variable scope behaves exactly as the one in C++. +In general, variable scope helps programs use less memory by not holding expired (a.k.a., no longer useful) information inside the memory. As an example: ```cpp int number = 10; @@ -167,9 +167,9 @@ void my_func2() { } ``` -In this case my_number doesn't exist inside *my_func2*, it only exists inside *my_func1* and only for the duration of that function's execution. +In this case, my_number doesn't exist inside *my_func2*, it only exists inside *my_func1*, and only for the duration of that function's execution. -Statements such as `if`, `else`, `for`, `while`, `try`, etc. create local variable scopes each time, meaning that variables declared inside them cannot be accessed outside of them, contrary to how for example Python handles it (where scopes are only created inside functions). +Statements such as `if`, `else`, `for`, `while`, `try`, etc. create local variable scopes each time, meaning that variables declared inside them cannot be accessed outside of them. This is contrary to how, for example, Python handles it (where scopes are only created inside functions). In AS, global variables are allowed, however: @@ -177,4 +177,4 @@ In AS, global variables are allowed, however: > From the official documentation: *Variables of primitive types are initialized before variables of non-primitive types. This allows class constructors to access other global variables already with their correct initial value. The exception is if the other global variable also is of a non-primitive type, in which case there is no guarantee which variable is initialized first, which may lead to null-pointer exceptions being thrown during initialization.* > [!TIP] -> A good practice is to avoid global variables altogether, and use different means of sharing information between functions such as returning values or &out references (more on that in later chapters). \ No newline at end of file +> A good practice is to avoid global variables altogether, and use different means of sharing information between functions (such as returning values or &out references - more on that in later chapters). \ No newline at end of file diff --git a/docs/angelscript/guide/Language Basics/chapter3.md b/docs/angelscript/guide/Language Basics/chapter3.md index b3f30c4e..d4a4538b 100644 --- a/docs/angelscript/guide/Language Basics/chapter3.md +++ b/docs/angelscript/guide/Language Basics/chapter3.md @@ -14,19 +14,19 @@ In this chapter you will learn about: - [Foreach](#foreach) - [Continue/Break keywords](#special-keywords) -> Loops are a way to make the code repeat itself a certain amount of times, of which the amount of repetitions may vary depending on what is going on in the code. +> Loops are a way to make the code repeat itself a certain amount of times. The amount of repetitions may vary depending on what is going on in the code. --- ### Arrays - Short Introduction > [!NOTE] -> This subsection is supposed to teach you the very basics of arrays, because next you will learn about loops, and loops are mostly useful for array manipulation. -> You won't learn in details what the array is and how to do operations on it, but you will learn how to create one and access its elements. +> This subsection is supposed to teach you the very basics of arrays. This is because in the following section you will be learning about loops, and loops are mostly useful for array manipulation. +> You won't learn in detail what an array is, nor how to do operations on them, but you will learn how to create one and access its elements. An array is an ordered group of elements, of which there is a starting element and an element at the end. -Code-wise it's a template object, as you need to specify of which data type its values will be. To create an array you can use the **{element, element2, ...}** assignment: +Code-wise, it acts a template object - you'll need to specify of which data type its values will be. To create an array, you can use the **{element, element2, ...}** assignment: ```cpp array@ a = {0, 1, 2, 3, 4}; @@ -35,9 +35,9 @@ array@ c = {.1, .3, .5}; ``` > [!NOTE] -> Since `array` and `dictionary` are value types, you initialize them as an object handles (the @ symbol). For now, just remember that you add that symbol after the type name, it will get explained later on. +> Since `array` and `dictionary` are value types, you initialize them as an object handle (the @ symbol). For now, just remember that you add that symbol after the type name - this will get explained later on. -To access elements in an array you use the index operator **[]**, where `[i]` will access the i'th element of the array (counting from 0): +To access elements in an array, you will use the index operator **[]**, where `[i]` will access the i'th element of the array (counting from 0): ```cpp a[3] // = 3 @@ -45,7 +45,7 @@ b[1] // = false b[0] // = .1 ``` -More on the arrays will be talked about in later parts of this guide. +More on arrays will be covered in later parts of this guide. --- @@ -75,7 +75,7 @@ do { ``` > [!WARNING] -> It is possible to create a never ending loop, the easiest way is to do `while (true)`. Such loops are most of times an error in programming. However, these loops can be an intentional decision when **you are sure the loop will at some time stop executing**, either with the `break` statement (more on that in a bit) or other ways. +> It is possible to create a never-ending loop. The easiest way to achieve this is with `while (true)`. Such loops are usually a programming error. However, these loops can be an intentional decision when **you are sure the loop will at some time stop executing**, either with the `break` statement (more on that in a bit) or through other ways. > ### TASK 1: > Write a program that will print out "Hello again!" to the console 10 times. @@ -94,22 +94,22 @@ An example of a `for` loop can be a loop that cycles through every character in array@ numbers = {1, 1, 2, 3, 5, 8, 13}; for (int i = 0; i < numbers.length(); i++) { // For every i until i is greater or equal to the array length (this will ensure i won't go out of bounds) numbers[i] // Represents the i'th number in the array - // After executing code do i++ (add one to i), so we can access the next element + // After executing code, do i++ (add one to i), so we can access the next element } ``` > [!TIP] -> Statements 1 and 3 in for loops can be skipped, as an example `for (;condition;)` is a valid form of a `for` loop, and so is `for (int a = 0;condition;)` etc. +> Statements 1 and 3 in for loops can be skipped. As an example, `for (;condition;)` is a valid form of a `for` loop, and so is `for (int a = 0;condition;)` etc. > ### TASK 2: > -> Given an array of integers, write a program that will add all of these integers and print out the result. +> Given an array of integers, write a program that will add all of them together and print out the result. > > [!NOTE] -> > Because of the [Variable Scope](chapter3/#variable-scope), you will need to define a variable to store the sum outside of the loop. +> > Because of [variable scope](chapter3/#variable-scope), you will need to define a variable to store the sum outside of the loop. ## Foreach -A `foreach` loop can be used to perform code for each item in a container objects. Container objects are objects that store values of other data types, such as the `array` object or the `dictionary` object. Its structure `foreach (vars : container_object)` consists of two parts: where vars contains declarations of the variable names, such as `int val`, and the container object is the, well, container object. Some objects unpack more than one variable, such as the `dictionary` objects that unpacks the key and the appropriate value. +A `foreach` loop can be used to perform code for each item in a container object. Container objects are objects that store values of other data types, such as the `array` object or the `dictionary` object. Its structure (`foreach (vars : container_object)`) consists of two parts. `vars` contains declarations of the variable names, such as `int val`, and `container_object` acts as the container object. Some objects unpack more than one variable, such as `dictionary` objects, which unpack the key and the appropriate value. ```cpp array@ integers = {1, 2, 3, 4}; @@ -122,7 +122,7 @@ dictionary@ mydict = { {"key2", value2}, {"key3", value3} }; -foreach (auto value, auto key : mydict) {// NOTE: the order is flipped here, as compared to e.g. foreach in Squirrel (VScript), value goes first +foreach (auto value, auto key : mydict) { // NOTE: the order is flipped here compared to e.g. foreach in Squirrel (VScript). Value comes first // Loop through mydict } @@ -138,7 +138,7 @@ These are the special keywords that can be used inside loops. ### Break Statement -The `break` statement is a way to exit a loop execution early. Calling it will cause the program to abort loop execution and continue executing code after the loop. +The `break` statement is a way to exit a loop execution early. Calling it will cause the program to leave the loop early and continue executing code after the loop. ```cpp int a = 10; @@ -147,12 +147,12 @@ while (a > 0) { break; } } -// This loop will stop executing when a will be equal to 5 +// This loop will stop executing when a equals 5 ``` ### Continue Statement -The `continue` statement will cause the loop to stop and go to the next element. +The `continue` statement will skip the current iteration, causing the loop to stop and go to the next element. ```cpp int sum = 0; @@ -176,12 +176,15 @@ while (condition) { for (int a = 5; a < 10; a++) { if (a > 5) { - break; // This will break of the for loop, not the while loop! + break; } } } ``` +The code will break of the `for` loop, but not the `while` loop. + + > ### TASK 4: > > Create a **while (true)** loop that adds all integers until 20. diff --git a/docs/angelscript/guide/Language Basics/chapter4.md b/docs/angelscript/guide/Language Basics/chapter4.md index cd44be14..2d24db08 100644 --- a/docs/angelscript/guide/Language Basics/chapter4.md +++ b/docs/angelscript/guide/Language Basics/chapter4.md @@ -24,7 +24,7 @@ In this chapter you will learn about: ### Syntax -As you already know or not, functions are a way of implementing routines that operate on an input and produce a result. In Layman's terms, you give it some data, it processes the data and (may, but doesn't need to) give you an output. +Functions are a way of implementing routines that operate on an input and produce a result. In simple terms, you give a function data, it processes the data, and gives an output (although having an output is not necessary). A function declaration consists of 3 main parts: *return value*, *function name*, and the *parameters*. These follow pretty much the same syntax as C++: @@ -52,11 +52,11 @@ bool myFunction(int a, int b) { } ``` -Each function **must** have a return statement in each of its "paths". What that basically means, is that whatever you do in your function, it will always end with a return statement. The only exception is the `void` return type (which means return nothing), in which you can skip the `return` keyword entirely, or use the `return;` statement when you want to exit the function early. +Each function **must** have a `return` statement in each of its "paths". Whatever you do in your function, it must always end with a `return` statement. The only exception is the `void` return type (which means return nothing), in which you can skip the `return` keyword entirely, or use the `return;` statement when you want to exit the function early. ### Calling Functions -Calling functions in code is very simple, you use the **function call `()`** operator, `func(arguments)`. In it, you include every needed argument: +Calling functions in code is very simple using the **function call `()`** operator, `func(arguments)`. In it, you include every needed argument: > [!NOTE] > ""Variables"" in a function declaration are called **parameters**, while ""variables"" in a function call are called **arguments**. @@ -76,11 +76,11 @@ a = sum(a, just5()); // just5 will get evaluated first, then its result will get // a = 5 ``` -Calling a function is a statement, which means it can be freely used in expressions in every combination. You can treat `func(p)` as a value that you do operations with. +Calling a function is a statement, meaning it can be freely used in expressions in every combination. You can treat `func(p)` as a value that you do operations with. ### Calling Methods on Objects -Some objects such as `string` or `array` implement methods. For now, you can think of methods as functions that sit inside the object (variable), and operate on that object. You can invoke them by using the `.` operator and then the function call. +Some objects, such as `string` or `array`, implement **methods**. For now, you can think of methods as functions that sit inside the object, and operate on that object. You can invoke them by using the `.` operator and then the function call. ```cpp string mystr = "ABC"; @@ -88,13 +88,13 @@ string mystr = "ABC"; mystr.length(); // Returns the length of this string (3) ``` -For a list of available methods per each type please refer to the [types section](../../game/type) of this wiki. +For a list of available methods per each type, please refer to the [types section](../../game/type) of this wiki. > [!NOTE] > Primitive types (`int`, `float`, `bool`, etc.) don't implement any methods. ### Recursion -Like in any other language, a function can call itself. This is function is then called a *recursive* function. +In most, if not all, programming languages, a function can call itself. This function is called a *recursive* function. ### Calling template functions @@ -119,7 +119,7 @@ Function parameters in AngelScript can be a bit confusing, since AS has custom k ### Default Parameters -Sometimes you want to add additional functionality to your function, but for most cases you already know what it should do, although you still want to include a customizable option for fine-tuning. You can do that by default parameters. +Default parameters are used to add optional arguments to your function. If you don't have an input for one of your arguments, it can default to a certain value, but can still be set to a different value later in the code. Each parameter can have a default value assigned to it, like so: @@ -128,7 +128,7 @@ void myFunc(int a = 5, int b = 1) {...} ``` This function can be called with *0*, *1*, and *2* arguments, and each call will be valid. -Calling it with 0 arguments will mean that `a` will be set to `5`, and `b` to `1`. Calling it with one argument will set a to that arguments value and so on. +Calling it with 0 arguments will mean that `a` will be set to `5`, and `b` to `1`. Calling it with one argument will set a to that argument's value, and so on. ```cpp myFunc(); // a = 5, b = 1 @@ -143,23 +143,22 @@ myFunc(2, 5); // a = 2, b = 5 ### Constant parameters -Constant parameters work just like constant variables. If declare a certain parameter constant, you won't be able to change it in any way. +Constant parameters work just like constant variables. If you declare a certain parameter as constant, you won't be able to change it in any way after declaring it. ```cpp void myFunc(const int a, const bool y = true) // Default parameters can also be constants ``` -One important note is that declaring a const parameter will make the compiler not copy the object (if it ensures the object's lifetime). More on that will be in the next chapters. - > ### TASK 1: > > Create a function that computes the nth number of the Fibonacci sequence. It should take uint as the parameter (n) and return an uint (the number). You can tackle this problem recursively (using recursion) or iteratively (using a loop). It is recommend to try out both. ### References - Short Intro -Before we delve into the next subchapter, you need to know what *references* are. In each computer, variables are stored in memory. You can visualize computers memory as a some sort of a box with labels. Each label has some space that it describes, and there can be an item in each label. Such items are our variables, and these labels are memory addresses. In such way, the computer knows where to look for these variables when it needs to find them. + +Before we delve into the next subchapter, you need to know what *references* are. In every computer, variables are stored in its memory. You can visualize a computer's memory as a box with labels. Each label describes a space within the box, with room in each space for items. Such items are our variables, and these labels are memory addresses. Using these, the computer knows where to look for these variables when it needs to find them. -References are just the labels we have been comparing to, they *are* the address of the variable they correspond to. +References are just the labels we have been comparing to - the address of the variable they correspond to. They are denoted with the **&** symbol. Conceptually: @@ -168,13 +167,13 @@ string mystring = "lorem ipsum"; &mystring // Memory address of mystring ``` -In AngelScript you cannot directly manipulate references, but you can do many useful things when you combine functions and references. The AngelScript compiler will automatically manage referencing (getting a variables address) and dereferencing (looking up a variable from an address). +In AngelScript, you cannot directly manipulate references, but you can do many useful things by combining functions and references. The AngelScript compiler will automatically manage referencing (getting a variable's address) and dereferencing (looking up a variable from an address). ### Reference Parameters Functions can be set to use references as parameters. -In the examples shown above every argument was **copied**. Here's a better example: +In the examples shown above, every argument was **copied**. Here's a better example: ```cpp void func(int c) {...} @@ -183,11 +182,11 @@ int a = 1; func(a); ``` -In this example, before `c` gets assigned a value from `a`, the value of `a` gets copied first, and only after that the assignment occurs. This happens, so that doing any operations on `c` in `func` will not cause `a` outside the function to change in any way. +In this example, before `c` gets assigned a value from `a`, the value of `a` gets copied first, and only after that will the assignment occur. This way, doing any operations on `c` in `func` will not cause the value of `a` to change in any way. -However, passing by reference changes that mechanism. Since now, the thing that gets copied is the memory address, not the actual variable value. Meaning that if we were to pass by reference in `func` above, doing any operation such as `c = 5;` would cause `a` to change accordingly (a = 5). +Using a pass by reference changes this mechanism by making the copied excerpt the memory address rather than the actual variable value. If we were to pass by reference the `func` above, doing any operation such as `c = 5;` would cause `a` to change accordingly (a = 5). -Telling the compiler that you want to pass by reference gets done in the function parameters declaration, like so: +Telling the compiler that you want to pass by reference is done in the function parameters declaration, like so: ```cpp void func(int& c) // This is a pass by reference @@ -197,20 +196,21 @@ No special syntax for calling is needed: ```cpp int a = 1; -func(a); // a gets passed by reference +func(a); // a gets pass by referenced ``` -AngelScript implements more functionality to passing by reference, and that includes 2 options: +AngelScript implements more functionality to pass by references, and that includes 2 options: #### &in +?????????????????????????? second sentence This marks the parameter as an input to the function. This option provides little to no benefit as to just passing by value (copying), as the compiler still has to ensure the object won't get modified outside the function, and the only way to do that is to make a copy. > [!TIP] -> Combining `&in` with `const` can however, yield a way more optimized code. `&in` should almost always be used whenever you are using a `const` parameter. +> Combining `&in` with `const` can, however, yield more optimized code. `&in` should almost always be used whenever you are using a `const` parameter. > [!WARNING] -> Primitive types should not be passed with `&in`, as the memory address still has to be copied over, resulting in the same hit of performance (or worse!) as just copying the value itself. +> Primitive types should not be passed with `&in`, as the memory address still has to be copied over, resulting in the same hit on performance (or worse!) as just copying the value itself. #### &out @@ -245,7 +245,7 @@ WholeDivision(10, 3, myresult, myrest); //This will set myresult and myrest to t #### &inout / & -This option specifies that this parameter will be passed by reference in both directions. Meaning, the argument will not be copied, and also any changes made to this variable will result in a modified state of the argument outside the function. +This option specifies that this parameter will be pass by referenced in both directions. This means that the argument will not be copied, and also that any changes made to this variable will result in a modified state of the argument outside the function. > [!NOTE] > `&inout` or `&` are **not** supported for primitive types. @@ -254,7 +254,7 @@ This option specifies that this parameter will be passed by reference in both di ## Returning references -Functions can also *return* references. Meaning that they return an address to an object, rather than the object itself. In previous examples we have discussed functions that return by value, meaning that the value of the variable that gets returned, gets copied to a temporary location and then gets "transferred" over to the variable outside the function: +Functions can also *return* references. This means they can return an address to an object, rather than the object itself. In previous examples, we have discussed functions that return by value, meaning the value of the variable that gets returned gets copied to a temporary location and then gets "transferred" over to the variable outside the function: ```cpp int func(int a) { @@ -267,9 +267,9 @@ b = func(2); // Result of func(2) gets stored in a temporary location and then c func(2) = 1; // This will not work. ``` -Returning references works in a different way, we return an address, that means the actual value of the variable never gets copied which saves on performance. Additionally, it allows you to do operations on the return value of a function. To declare a function that returns a reference, you append the `&` symbol at the end of the type name in the return type. +Returning references works differently. Here, we return an address - meaning the actual value of the variable never gets copied, saving on performance. Additionally, it allows you to do operations on the return value of a function. To declare a function that returns a reference, you append the `&` symbol at the end of the type name in the return type. -Before we overview examples, there is one more thing to discuss about returning references. Not every variable can get it's reference returned. In general, variables that don't exist outside the function will not be able to get returned by reference, because they will get erased once the code gets out of the function. +Before we go over some examples, there is one more thing to discuss about returning references. Not every variable can get its reference returned. In general, variables that don't exist outside the function will not be able to get returned by reference, because they will get erased once the code gets out of the function. ### 1. References to global variables are allowed. @@ -283,16 +283,16 @@ int& addToA(int b) { return a; // Like in reference parameters, no additional syntax is needed. } -//This will allow us to do something like: +// This will allow us to do something like: addToA(1) = 3; // We add 1 to a, but then we change a to be equal to 3. ``` ### 2. References to class members and `this` are allowed. > [!NOTE] -> This information will be useful once we get to custom classes and reference types, so if you don't know what these are you can skip this for now. +> This information will be useful once we get to custom classes and reference types. If you don't know what those are, you can skip this for now. -References to class members (properties) and to ourselves (`this`) are allowed to be returned by methods. +References to class members (properties) and to ourselves (`this`) are allowed to be returned by methods: ```cpp class myclass { @@ -308,9 +308,11 @@ class myclass { } ``` -### 3. Returning a reference to a local variable is not allowed. +??????????????????????????? does underlining work + +### 3. Returning a reference to a __local__ variable is **not** allowed. -Returning a reference to a local variable is not allowed, this is because the variable will not exist after the function returns. +Returning a reference to a local variable is not allowed. This is because the variable will not exist after the function returns. ```cpp int& myFunc() { @@ -319,7 +321,7 @@ int& myFunc() { } ``` -### 4. Returning a reference to a deferred parameter is not allowed. +### 4. Returning a reference to a deferred parameter is **not** allowed. Values passed by reference into a function cannot be returned by reference. This is because AS does additional cleanup after the function returns, hence why there is no guarantee that an object passed by `&in`/`&out` will exist after the function returns. @@ -331,13 +333,13 @@ int& func(int a&in ) { > ### TASK 2: > -> Create a function that splits a string into two same-length parts. It should take a string and return a boolean if the string can be split (if the strings length is not divisible by two you cannot create two equal-length parts), and it should also return these two parts (use `&out`). +> Create a function that splits a string into two same-length parts. It should take a string and return a boolean if the string can be split (if the string's length is not divisible by two, you cannot create two equal-length parts), and it should also return these two parts (use `&out`). --- ## Function Overloads -Function overloading is a very powerful concept, as it allows you to declare a function multiple times, each time with a different set of parameters. The compiler will then attempt to choose the best "fit" for which exact function to call (the criteria of how it does so are available on the [official documentation](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_script_func_overload.html)). +Function overloading is a very powerful concept, as it allows you to declare a function multiple times, each time with a different set of parameters. The compiler will then attempt to choose the best "fit" for which exact function to call (the criteria of how it does so is available on the [official documentation](https://www.angelcode.com/angelscript/sdk/docs/manual/doc_script_func_overload.html)). This is mainly used for functions that can accept multiple combinations and types of parameters, but produce a similar result. @@ -351,7 +353,7 @@ myFunc(10.5); // Will call the first option (but float will get converted to int myFunc(false); // Will cause an error since none of the options specify bool as a parameter ``` -Default parameters are also allowed to be used in overloading, but you have to be careful whilst doing so. If you define your function wrong, the compiler will not be able to decide whether it should use an overload or use a default parameter. +Default parameters are also allowed to be used in overloading, but you have to be careful whilst doing so. If you define your function wrong, the compiler will not be able to decide whether it should use an overload or use a default parameter: ```cpp void myFunc(int a, int b = 2) {...} @@ -369,11 +371,11 @@ myFunc(1, "A"); // Will work ``` > [!WARNING] -> Different return types are allowed for overloads, e.g. one function can return an int, whilst other can return a string (the auto keyword is useful here); however the compiler will not take the return type as a criteria for deciding which overload to use. +> Different return types are allowed for overloads, e.g. one function can return an int, whilst another can return a string (the auto keyword is useful here). The compiler will not take the return type as a criteria for deciding which overload to use. > ### TASK 3: > -> In the default parameters section there was a problem mentioned about how you cannot explicitly set custom parameters. Given a function: +> In the default parameters section, there was a problem mentioned about how you cannot explicitly set custom parameters. Given a function: > >```cpp > int printXTimes(string msg, string end = "\n", int x = 1) { @@ -383,7 +385,7 @@ myFunc(1, "A"); // Will work > } > ``` > -> Find a way to use it to print 10 times the message "CONSOLE SPAM!" **without specifying a value for the `end` parameter!** +> Find a way to use it to print the message "CONSOLE SPAM!" ten times, **without specifying a value for the `end` parameter!** > > [!TIP] > > You can call an overload to a different function in an overloaded function: > >