feat: streams

Author: tolstenko

README.md

@@ -10,6 +10,10 @@ time for you to revisit them.
 2. [Developer Portfolio](portfolio/README.md)
 3. [Artificial Intelligence](artificialintelligence/README.md)
 
+# Philosophy
+
+Before we start, this repository aims to be practical, and it will be updated as I test the methodology. Frame it as a guidebook, not a manual. Most of the time, I am constrained by the time, so in order to move fast, I don't cover deeply some topics, but the basics that allows you to explore by yourself or point the directions for you to study in other places acting as a self-taught student, so you really should look for more information elsewhere if you feels so. I use lots of references and highly incentive you to look for other too and propose changes in this repo. Sometimes, I will mostly try to teach in a chaotic way, which implies that you will need to explore the concepts by yourself or read the manual/books. Every student should follow your own path to learning, it is impossible for me to cover every learning style, so it is up to you to build your own path and discover the best way to learn. What worked for me or what works for a given student probably wont work for you, so dont compare yourself to others too much, but be assured that I am here to help you to succeed. If you need help, just send me a message in private, or use public forums such as github issues and discussions.
+
 # Badges
 
 CI: [![Documentation](https://github.com/InfiniBrains/Introduction-to-Game-Programming-With-CPP/actions/workflows/documentation.yaml/badge.svg)](https://github.com/InfiniBrains/Introduction-to-Game-Programming-With-CPP/actions/workflows/documentation.yaml) 

intro/01-introduction/README.md

@@ -1,5 +1,9 @@
 # Reasons why you should learn how to program with C++
 
+Before we start, this repository aims to be practical, and I highly incentive you to look for other references. I want to add this another [awesome repository](https://github.com/federico-busato/Modern-CPP-Programming/) it holds an awesome compilation of modern C++ concepts.
+
+Another relevant reference for what we are going to cover is the [updated core guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) that explain why some syntax or style is bad and what you should be doing instead.
+
 ## Why?
 
 The first thing when you think of becoming a programmer is **HOW DO I START?** Well, **C++** is one of the best 

intro/06-functions/README.md

@@ -155,7 +155,7 @@ int main()
 
 # Passing parameter to a function by reference
 
-Pass-by-reference occurs when the function parameter uses the `&` in the parameter declaration. It will allow the function to modify the value of the parameter directly in the other scope, rather than making a copy of the value as it does with pass-by-value.
+Pass-by-reference occurs when the function parameter uses the `&` in the parameter declaration. It will allow the function to modify the value of the parameter directly in the other scope, rather than making a copy of the value as it does with pass-by-value. The mechanism behind the variable passed is that it is an alias to the outer variable because it uses the same memory position.
 
 ```c++
 #include <iostream>
@@ -172,6 +172,73 @@ int main() {
 }
 ```
 
+# Passing parameter to a function by pointer
+
+Pass-by-pointer occurs when the function parameter uses the `*` in the parameter declaration. It will allow the function to modify the value of the parameter in the other scope via memory pointer, rather than making a copy of the value as it does with pass-by-value. The mechanism behind it is to pass the memory location of the outer variable as a parameter to the function.
+
+```c++
+#include <iostream>
+using namespace std;
+void times2(int *x) { // by using *, x has the same address the variable passed where the function is called
+    // x holds the address of the outer variable
+    // *x is the content of what x points.
+  *x *= 2; // it will change the variable in caller scope
+}
+
+int main() {
+  int y = 2;
+  times2(&y); // the function expects a pointer, given pointer is an address, we pass the address of the variable here
+  cout << y << endl;  // Outputs 4
+  return 0;
+}
+```
+
+# Function overload
+
+A function with a specific name can be overload with different not implicitly convertible parameters.
+
+```c++
+#include <iostream>
+using namespace std;
+
+float average(float a, float b){
+    return (a + b)/2;
+}
+
+float average(float a, float b, float c){
+    return (a + b + c)/3;
+}
+
+int main(){
+    cout << average(1, 2) << endl; // print 1.5
+    cout << average(1, 2, 3) << endl; // print 2
+    return 0;
+}
+```
+
+# Default parameter
+
+Functions can have default parameters that should be used if the parameter is not provided, making it optional.
+
+```c++
+#include <iostream>
+using namespace std;
+
+void greet(string username = "user") {
+    cout << "Hello " << mes << endl;
+}
+
+int main() {
+  // Prints "Hello user"
+  greet(); // the default parameter user is used here
+
+  // Prints "Hello John"
+  printMessage("John");
+  
+  return 0;
+}
+```
+
 # Scopes
 
 Scope is a region of the code where a identifier is accessible. A scope usually is specified by what is inside `{` and `}`. The global scope is the one that do not is inside any `{}`.

intro/07-streams/README.md

@@ -4,6 +4,51 @@ At this point, you already are familiar with the `iostream` header. But we never
 
 But C++ have 2 other relevant streams that we need to cover: [`fstream`](https://en.cppreference.com/w/cpp/header/fstream) and [`sstream`](https://en.cppreference.com/w/cpp/header/sstream).
 
+# File streams
+
+File streams are streams that target files instead of the terminal console. The [`fstream` header](https://en.cppreference.com/w/cpp/header/fstream) describes the file streams and the ways you can interact with it.
+
+The main differences between console and file streams are:
+- You have to target the filesystem path for files because we can manage different files at the same, but for console, you only have one, so you dont need to target which console we are streaming. In order to not mess each target, you have to declare a different variable to store the target and state.
+- Files are persistent, so if you write something to them, and try to read from it again, the that will be there saved.
+
+Files are a kind of resource managed by the operation system. So every time you request something to be read or write, behind the scenes you are requesting something to the operating system, and it can be slow or subject by lock control. When you open a file to be read or write, the OS locks it to avoid problems. You can open a file to be read multiple times simultaneously, but you cannot write more than once. So to avoid problems, after reading or writing the file, you should close the file.
+
+```c++
+#include <fstream>
+#include <iostream>
+#include <string>
+
+using namespace std;
+
+int main() {
+  // Open the file
+  // this file path is relative to the executable, so be assured it exists in the same folder the executable is placed
+  // fin is the variablename and it is function initialized via a file path to target, but it can be any valid identifier
+  // I am using fin as variable to follow the same metaphor `fin` as `file input` as we have with console input `cin`, 
+  ifstream fin("file.txt"); 
+
+  // Check if the file is open
+  // it is a good practice to check if the file is really there before doing anything
+  if (!fin.is_open()) {
+    cerr << "Error opening file" << endl;
+    return 1; // quits the program with an error code
+  }
+
+  // Read the contents of the file line by line
+  string line;
+  // getline can target streams in general, so you can pass the file stream as a target
+  while (getline(fin, line)) { // while the file have lines, read and store the content inside the line variable
+    cout << line << endl; // output each string into the console
+  }
+
+  // Close the file
+  fin.close();
+
+  return 0;
+}
+```
+
 # String Stream
 
 The [`sstream` header](https://en.cppreference.com/w/cpp/header/sstream) describes string stream, which is a type of memory stream and is very useful to do string manipulation. For our intent, we aro going to focus 3 types of memory streams.
@@ -47,6 +92,71 @@ int main() {
 }
 ```
 
-# File streams
+You can combine string stream and file stream to read a whole file and store into a single string.
+
+```c++
+#include <fstream>
+#include <iostream>
+#include <sstream>
+#include <string>
 
-File streams are streams 
+using namespace std;
+
+int main() {
+  // Open the file
+  ifstream file("file.txt");
+
+  // Check if the file is open
+  if (!file.is_open()) {
+    cerr << "Error opening file" << endl;
+    return 1;
+  }
+
+  // Read the contents of the file into a stringstream
+  stringstream ss;
+  ss << file.rdbuf(); // read the whole file buffer and stores it into a string stream
+
+  // Close the file
+  file.close();
+
+  // Convert the stringstream into a string
+  string contents = ss.str();
+
+  cout << contents << endl; // prints the whole file at once
+
+  return 0;
+}
+```
+
+# Homework
+
+You have the job of creating a small program to read a file image in the format PGMA and inverse the colors as a negative image.
+
+You can test your code with different images if you want. You can download more images [here](https://people.sc.fsu.edu/~jburkardt/data/pgma/pgma.html). But here goes 2 examples:
+
+- Sample input easy: [baboon.ascii.pgm](baboon.ascii.pgm) - max intensity is not 255 and don't have comments.
+- Sample input harder: [lena.ascii.pgm](lena.ascii.pgm) - have comments, and the max intensity is different than 255.
+
+You can test if your output file is correct using [this tool](https://www.gimp.org/). You can open this file via any text reader, use the online viewer, or use any app that reads pnm images.
+
+## Attention:
+
+- To create the inverse image, you should read the file header and search for the maximum intensity. You should use this number as a base to inverse. In the Lena case, it is 245.
+- You should pay attention that every line shouldn't be bigger than 70 chars;
+- Pay attention that the line 2 might exists or not. And any comment found in the file should be skipped.
+
+The user should input the filename to be read. So you should store it into a string variable. The output filename should be the same as the input but with '.inverse' concatenated in the end. Ex.: lena.pgm becomes lena.inverse.pgm; If you find this too complicated, just concatenate with .inverse.pgm would be acceptable. ex.: lena.pgm becomes lena.pgm.inverse.pgm
+
+In order for your program to find the file to be read, you should provide the fullpath to the file or simply put the file in the same folder your executable is.
+
+HINT:
+In order to find comments and ignore them do something like that:
+```c++
+string widthstr;
+int width;
+fin >> widthstr;
+if(widthstr.at(0)=='#')
+    getline(fin, widthstr); // ignore line
+else
+    width = stoi(widthstr); // covert string to integer
+```