Update 2024-01-25-lesson0.md

Author: stream-rahul

_posts/2024-01-25-lesson0.md

@@ -6,9 +6,9 @@ categories: rust
 permalink: /lesson0/
 ---
 
-# Lesson 0: CP
+## Lesson 0: CP
 
-# Co relation to the C language usage
+## Co relation to the C language usage
 
 1. **Args**: `env::args()` ↔ `argc/argv` (Rust is type-safe)  
 2. **Files**: `File::open()` ↔ `fopen()` (`Result<>` vs `NULL`)  
@@ -17,182 +17,168 @@ permalink: /lesson0/
 5. **Memory**: Auto `drop()` ↔ Manual `fclose()`  
 6. **Exit**: `process::exit()` ↔ `exit()` (same codes)
 
+## Rust Concepts for this Lesson
 
+1. **Result Type**: Rust uses `Result<T, E>` for error handling
+   - `Ok(T)`: Success case with value of type T
+   - `Err(E)`: Error case with error of type E
+
+2. **File Operations**:
+   - Uses the `std::fs::File` struct
+   - File operations return `Result` types
+   - Automatic resource cleanup via RAII
+
+3. **Ownership Model**:
+   - Each value has a single owner
+   - Owner is responsible for cleanup
+   - Ensures memory safety without garbage collection
+
+4. **Error Handling**:
+   - Pattern matching with `match`
+
+5. **Command Line Arguments**:
+   - Safe iteration over arguments
+   - UTF-8 validation built-in
 
 ```rust
+
+
+// Variable (1): `args`. Type: `Vec<String>`. Stores
+// command-line arguments as strings, where args[0] is
+// the program's path.
+// Domain: Vector of strings from command line.
+// Range: Depends on number of args passed.
+// Edge: Empty args, too few or many args given.
+
 use std::env;
 use std::fs::File;
 use std::io::{Read, Write};
 use std::process;
 
-// BUF_SIZE: The size of the buffer used for reading and writing
-// files (1).
-//          Represents the maximum number of bytes read/written in
-//          a single operation.
-//          Set to 256 bytes, implying a trade-off between system
-//          call overhead and memory usage.
-//          A larger buffer might reduce system calls but increase
-//          memory consumption.
-//          A smaller buffer might increase system calls but reduce
-//          memory consumption.
-//          The optimal value depends on the specific I/O
-//          characteristics and system resources.
-//          Choosing a power of 2 often aligns with memory page
-//          sizes, potentially improving efficiency.
-//          Example: If reading a 1KB file, 4 read operations would
-//          be required (1024 bytes / 256 bytes/read).
-const BUF_SIZE: usize = 256; // 2^8 = 256
+// Constant (2): `BUF_SIZE`. Type: `usize`.
+// Defines fixed size of data buffer.
+// Domain: Positive integers, max depending on platform.
+// Range: 256, memory safety constraint
+// Edge:  If too big, causes stack overflow, too small
+// then many more reads and writes, perf impact
+
+const BUF_SIZE: usize = 256;
 
 fn main() {
-    // args: A vector of strings representing the command-line
-    // arguments passed to the program (2).
-    //       args[0] is the program name itself.
-    //       args[1] is expected to be the input file path.
-    //       args[2] is expected to be the output file path.
-    //       Example: If executed as "./my_program input.txt
-    //       output.txt",
-    //                args[0] would be "./my_program", args[1] would be
-    //                "input.txt", and args[2] would be "output.txt".
-    let args: Vec<String> = env::args().collect(); // Vec<String> signifies
-    // a dynamically sized array of String objects, meaning it can store
-    // a variable number of strings.
-
-    // (3) Check if the correct number of arguments is provided
-    // (program name, input file, output file).
-    //  args.len(): Returns the number of elements in the vector
-    //  `args`.  In this code, it checks if exactly two arguments (input
-    //  and output files) are given in addition to the executable name.
-     if args.len() != 3 {  // 3 represents the expected number of
-     // arguments: program name + input file path + output file path
-        // eprintln!: Prints an error message to the standard error
-        // stream (stderr). This is commonly used to display error
-        // messages to the user in the console without cluttering the
-        // standard output.
-        //{}: A placeholder in the format string that will be
-        // replaced with the corresponding argument.
-        eprintln!("Usage: {} file1 file2", args[0]); // args[0] is
-        // always the program name, which provides context to the
-        // error message
-
-        // process::exit(1): Terminates the program with an exit code
-        // of 1. Non-zero exit codes conventionally indicate an error.
-        // 1: Signifies a general error exit code. This tells the
-        // operating system or calling process that the program
-        // encountered an issue. Different exit codes can be used to
-        // signal different types of errors.
-         process::exit(1); // Exit with a non-zero status code
-         // indicating an error. 1 is a common code for general errors.
+    // Variable (3): `args`. Type: `Vec<String>`. Stores command
+    // line args. Purpose is processing file copies
+    // based on input args.
+    let args: Vec<String> = env::args().collect();
+
+    // Control Flow (4): Conditional `if`. Checks if number
+    // of command line args is exactly 3 (program name,
+    // input file path and output file path)
+    // Edge Case: `args.len()` too short, too long.
+    if args.len() != 3 {
+        // Operation (5): Prints usage info on stderr.
+        // Implies error in number of args.
+        eprintln!("Usage: {} file1 file2", args[0]);
+        // Operation (6): Terminate program with failure
+        // code. Indicates incorrect usage.
+        process::exit(1);
     }
 
-    // (4) Attempt to open the input file specified by the first
-    // command-line argument (`args[1]`).
-    // File::open(&args[1]): Attempts to open the file specified by
-    // `args[1]` in read-only mode. Returns a `Result<File, Error>`.
-    // match: A pattern-matching construct that handles different
-    // outcomes of the `Result`.
-        let mut in_file = match File::open(&args[1]) {  // Attempt to
-        // open the input file. args[1] contains the file path
-        // provided as the first command-line argument.
-        Ok(file) => file,                // If successful, assign the
-        // opened file to `in_file`.
-        Err(err) => {                  // If an error occurs during
-        // file opening...
-            eprintln!("{}: {}", args[1], err);  // Print an error
-            // message indicating the file that couldn't be opened and
-            // the reason.
-            process::exit(2);          // Exit with a non-zero status
-            // code (2) indicating a file opening error.
+    // Variable (7): `in_file`. Type: `File`. Represents
+    // input file object which is opened for reading.
+    // Purpose is to read contents from it.
+    // Sub unit : File handle.
+    // Result: `File`, or `Err`.
+    let mut in_file = match File::open(&args[1]) {
+        // Control Flow (8): `match` expression on `Result`.
+        // `Ok` path opens file, `Err` handles open failure.
+        Ok(file) => file,
+        // Control Flow (9): Error handler for file open.
+        Err(err) => {
+            // Operation (10): Prints error details of open on
+            // stderr. Indicates file access failure.
+            eprintln!("{}: {}", args[1], err);
+            // Operation (11): Exits program due to open
+            // failure. Input file is critical.
+            process::exit(2);
         }
     };
 
-
-    // (5) Attempt to create the output file specified by the second
-    // command-line argument (`args[2]`).
-    //File::create(&args[2]) : Attempts to create a new file at the
-    // path specified by `args[2]`. If the file already exists, it will
-    // be truncated (overwritten). It returns a Result<File, Error>.
-    let mut out_file = match File::create(&args[2]) { // Attempt to
-    // create the output file. args[2] contains the file path
-    // provided as the second command-line argument.
-        Ok(file) => file,                  // If successful, assign the
-        // created file to `out_file`.
-        Err(err) => {                    // If an error occurs during
-        // file creation...
-            drop(in_file);               // Close the input file to
-            // release the resource.
-            eprintln!("{}: {}", args[2], err);    // Print an error
-            // message indicating the file that couldn't be created and
-            // the reason.
-            process::exit(3);              // Exit with a non-zero
-            // status code (3) indicating a file creation error.
+    // Variable (12): `out_file`. Type: `File`. Represents
+    // output file object which is opened for writing.
+    // Purpose is to write contents to it.
+    // Sub unit : File handle.
+    // Result: `File`, or `Err`.
+    let mut out_file = match File::create(&args[2]) {
+        // Control Flow (13): `match` expression on `Result`.
+        // `Ok` creates file, `Err` handles create failure.
+        Ok(file) => file,
+        // Control Flow (14): Error handler for file create.
+        Err(err) => {
+            // Operation (15): Prints error details of file
+            // create on stderr. Indicates file creation fail.
+            eprintln!("{}: {}", args[2], err);
+            // Operation (16): Exits program due to create
+            // failure. Output file is critical.
+            process::exit(3);
         }
     };
 
+    // Variable (17): `buffer`. Type: `[u8; BUF_SIZE]`.
+    // Fixed size buffer to store data read from input
+    // file. Data unit: fixed size array of bytes.
+    // Size: BUF_SIZE bytes.
+    let mut buffer = [0u8; BUF_SIZE];
 
-    // buffer: A fixed-size array of unsigned 8-bit integers (bytes)
-    // used as a temporary storage for reading and writing data (6).
-    //        Initialized with zeros.
-    //        The size is determined by BUF_SIZE (256 bytes).  This array
-    // acts as an intermediary storage location for chunks of data read
-    // from the input file and before they are written to the output file.
-     let mut buffer = [0u8; BUF_SIZE]; // Create a buffer to hold
-     // chunks of data read from the input file. It's initialized
-     // with 0s.
-
-
-    // (7) Loop to read from the input file and write to the output
-    // file until the end of the input file is reached.
-    // loop: An infinite loop that continues until explicitly broken
-    // using `break`.
+    // Control Flow (18): Infinite `loop`. Reads data from input file,
+    // writes data to output file, terminates when
+    // end-of-file is reached or error occurs
     loop {
-        // (8) Read bytes from the input file into the buffer.
-        // in_file.read(&mut buffer): Attempts to read bytes from
-        // `in_file` into the `buffer`. Returns a `Result<usize, Error>`.
-        //  `usize`: Represents the number of bytes successfully read.
-         let bytes_in = match in_file.read(&mut buffer) {  // Read from
-         // the input file into the buffer.
-            Ok(n) => n,                        // If successful, `n` is
-            // the number of bytes read. Assign it to `bytes_in`.
-            Err(err) => {                      // If an error occurs
-            // during reading...
-                eprintln!("Error reading file: {}", err); // Print an
-                // error message.
-                process::exit(4);                  // Exit with a
-                // non-zero status code (4) indicating a file reading
-                // error.
+        // Variable (19): `bytes_in`. Type: `usize`. Stores
+        // number of bytes read from the file in current iteration.
+        // Domain: Non-negative integers <= BUF_SIZE.
+        // Range: 0 to BUF_SIZE.
+        let bytes_in = match in_file.read(&mut buffer) {
+            // Control Flow (20): `match` for result from read.
+            // `Ok` provides number of bytes read.
+            Ok(n) => n,
+            // Control Flow (21): Error handler for read errors.
+            Err(err) => {
+                // Operation (22): Prints file read error to stderr.
+                // Indicates low level file system issues.
+                eprintln!("Error reading file: {}", err);
+                // Operation (23): Terminates program on read error.
+                // Input file data is necessary.
+                process::exit(4);
             }
         };
 
-        // (9) Check if the end of the input file has been reached.
-        // bytes_in == 0 : Checks if the number of bytes read
-        // (`bytes_in`) is zero.  A zero byte read indicates the end
-        // of the file has been reached.
-         if bytes_in == 0 {      // If no bytes were read, it means
-         // the end of the file has been reached.
-            break;                 // Exit the loop.
+        // Control Flow (24): Checks for end-of-file condition.
+        // Checks if bytes read in last read were zero.
+        if bytes_in == 0 {
+            // Operation (25): Breaks infinite loop upon EOF.
+            // Terminates read write cycle.
+            break;
         }
 
-        // (10) Write the bytes read from the buffer to the output
-        // file.
-        // out_file.write_all(&buffer[..bytes_in]): Attempts to
-        // write all bytes from the `buffer` up to the index
-        // `bytes_in` to the `out_file`. Returns a `Result<(), Error>`.
-          if let Err(err) = out_file.write_all(&buffer[..bytes_in]) {
-          // Write the data from the buffer to the output file.
-          // &buffer[..bytes_in] creates a slice of the buffer
-          // containing only the bytes that were read.
-            eprintln!("Fatal write error: {}", err); // If an error
-            // occurs during writing, print an error message.
-            process::exit(4);                     // Exit with a
-            // non-zero status code (4) indicating a file writing
-            // error. Why 4? Potentially reusing the same error code
-            // for read/write errors for simplicity, or signifying a
-            // fatal error at this stage.
+        // Control Flow (26): Conditional `if let Err()`.
+        // Writes bytes read to output file, checks for error
+        if let Err(err) = out_file.write_all(&buffer[..bytes_in]) {
+            // Operation (27): Print error message on stderr.
+            //  Indicates critical failure in file write.
+            eprintln!("Fatal write error: {}", err);
+            // Operation (28): Terminate program upon write fail
+            // Output file write is necessary.
+            process::exit(5);
         }
     }
 }
+
+
+
+
+
 ```
 
-### Exercise
+## Exercise
 
 Let us do byte by byte copy, exactly one byte. Read exactly one, write exactly one. No more and no less.