Skip to content

Commit 1bf7bac

Browse files
ZahidFKhanZahidFKhan
committed
docs(stream): add comprehensive stream documentation
* Introduce multiple markdown files explaining stream concepts, characteristics, and usage in Java
1 parent 159074c commit 1bf7bac

12 files changed

Lines changed: 172 additions & 17 deletions

‎.github/prompts/smart-renaming.prompt.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
You are working on a codebase where files inside the folder $ARGUMENT need to be renamed, reordered, and fixed.
2+
3+
### Goal:
4+
1. Ensure all files in the folder are ordered in ascending alphabetical sequence based on their filename prefix.
5+
2. Each file must start with a single uppercase alphabet prefix followed by an underscore:
6+
Format: <ALPHABET> <Descriptive-name>.md
7+
8+
3. If multiple files currently share the same starting alphabet, rename them so that each file gets a unique sequential alphabet.
9+
10+
### Example:
11+
Current:
12+
A_SomeNameX.md
13+
A_SomeNameY.md
14+
A_SomeNameZ.md
15+
16+
Expected:
17+
A SomeNameX.md
18+
B SomeNameY.md
19+
C SomeNameZ.md
20+
21+
---
22+
23+
### Smart Renaming (IMPORTANT):
24+
- Improve the filename after the prefix to be meaningful, clean, and consistent.
25+
- Capitalize the first letter of each word in the file names.
26+
- Don't use hyphens use spaces to separate words in the descriptive part of the filename.
27+
- Derive better names from:
28+
- File content (title, headings, or main topic)
29+
- Existing filename (if already meaningful)
30+
31+
### Examples:
32+
A_tmp.md → A Introduction To System Design.md
33+
B_notes.md → B Database Indexing Strategies.md
34+
35+
### Rules for naming:
36+
- Lowercase only (except prefix)
37+
- Remove special characters
38+
- Keep names concise but descriptive
39+
- Do NOT change file extensions
40+
41+
---
42+
43+
### Navigation Links Fix (CRITICAL):
44+
Each `.md` file contains navigation links at the end (e.g., Previous / Next links).
45+
46+
After renaming:
47+
- Update all navigation links so they correctly point to the renamed files.
48+
- Ensure no broken links exist.
49+
- Maintain logical sequence:
50+
- "Previous" → previous file in alphabetical order
51+
- "Next" → next file in alphabetical order
52+
53+
---
54+
55+
### Constraints:
56+
- Preserve content integrity inside files (except navigation links update).
57+
- Do NOT overwrite files accidentally.
58+
- Handle edge cases:
59+
- Single file
60+
- Already correctly named files
61+
- Missing or malformed navigation links
62+
63+
---
64+
65+
### Output Requirements:
66+
Provide a complete working script (preferably Python, Bash, or Node.js) that:
67+
1. Reads all files in $ARGUMENT
68+
2. Generates improved filenames
69+
3. Renames files safely
70+
4. Updates navigation links inside `.md` files
71+
5. Prints a mapping:
72+
OLD_FILENAME → NEW_FILENAME
73+
74+
---
75+
76+
### Quality Requirements:
77+
- Code must be production-safe and idempotent
78+
- Use clear logic and comments
79+
- Avoid hardcoding filenames
80+
- Ensure cross-platform compatibility (if possible)

src/test/java/com/github/streams/learn/concepts/A. What is a Stream?.md renamed to src/test/java/com/github/streams/learn/concepts/A What Is A Stream.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,12 +58,12 @@ Output
5858
[5, 8, 9]
5959
```
6060

61-
> Pipeline execution is covered further in [Intermediate vs Terminal Operations](./E.%20Intermediate%20vs%20Terminal%20Operations.md).
61+
> Pipeline execution is covered further in [Intermediate vs Terminal Operations](./G%20Intermediate%20Vs%20Terminal%20Operations.md).
6262
6363
---
6464

6565
<div align="right">
6666

67-
[How to Create a Stream](./B.%20How%20to%20Create%20a%20Stream%3F.md) →
67+
[How to Create a Stream](./C%20How%20To%20Create%20A%20Stream.md) →
6868

6969
</div>

‎src/test/java/com/github/streams/learn/concepts/B Stream Characteristics.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Characteristics of a Stream
2+
3+
| Characteristic | What it means |
4+
|-------------------|--------------------------------------------------------------|
5+
| **Not a storage** | Streams carry data from a source; they do not hold it |
6+
| **Functional** | Operations take lambdas or method references, not statements |
7+
| **Lazy** | Intermediate steps do not execute until a terminal is called |
8+
| **Single-use** | Once a terminal operation runs, the stream is consumed |
9+
| **Possibly parallel** | Any stream can be made parallel with `.parallelStream()` |
10+
11+
---
12+
13+
## The Three Parts of a Pipeline
14+
15+
Every stream expression follows the same three-part structure:
16+
17+
```
18+
Source → Zero or more intermediate operations → One terminal operation
19+
```
20+
21+
```java
22+
var result = List.of(5, 3, 8, 1, 9, 2).stream() // 1. source
23+
.filter(n -> n > 3) // 2. intermediate
24+
.sorted() // 2. intermediate
25+
.toList(); // 3. terminal
26+
27+
System.out.println(result);
28+
```
29+
30+
Output
31+
```
32+
[5, 8, 9]
33+
```
34+
35+
> Pipeline execution is covered further in [Intermediate vs Terminal Operations](./G%20Intermediate%20Vs%20Terminal%20Operations.md).
36+
37+
---
38+
39+
<div align="right">
40+
41+
[How to Create a Stream](./C%20How%20To%20Create%20A%20Stream.md) →
42+
43+
</div>

src/test/java/com/github/streams/learn/concepts/B. How to Create a Stream?.md renamed to src/test/java/com/github/streams/learn/concepts/C How To Create A Stream.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,12 +73,12 @@ try (var lines = Files.lines(Path.of("src/test/resources/SonnetI.txt"))) {
7373
<tr>
7474
<td style="text-align: left;">
7575

76-
← [What is a Stream?](./A.%20What%20is%20a%20Stream%3F.md)
76+
← [What is a Stream?](./A%20What%20Is%20A%20Stream.md)
7777

7878
</td>
7979
<td style="text-align: right;">
8080

81-
[Primitive Streams](./C.%20Primitive%20Streams.md) →
81+
[Primitive Streams](./D%20Primitive%20Streams.md) →
8282

8383
</td>
8484
</tr>

src/test/java/com/github/streams/learn/concepts/C. Primitive Streams.md renamed to src/test/java/com/github/streams/learn/concepts/D Primitive Streams.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,12 @@ System.out.println(list); // [1, 2, 3, 4, 5]
3535
<tr>
3636
<td style="text-align: left;">
3737

38-
← [How to Create a Stream](./B.%20How%20to%20Create%20a%20Stream%3F.md)
38+
← [How to Create a Stream](./C%20How%20To%20Create%20A%20Stream.md)
3939

4040
</td>
4141
<td style="text-align: right;">
4242

43-
[Stream vs Collection](./D.%20Stream%20vs%20Collection.md) →
43+
[Stream vs Collection](./F%20Stream%20Vs%20Collection.md) →
4444

4545
</td>
4646
</tr>

‎src/test/java/com/github/streams/learn/concepts/E Stream Pipeline Structure.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
2+
# Structure of a Stream Pipeline
3+
4+
Every stream expression follows the same three-part structure:
5+
6+
```
7+
Source → Zero or more intermediate operations → One terminal operation
8+
```
9+
10+
```java
11+
var result = List.of(5, 3, 8, 1, 9, 2).stream() // 1. source
12+
.filter(n -> n > 3) // 2. intermediate
13+
.sorted() // 2. intermediate
14+
.toList(); // 3. terminal
15+
16+
System.out.println(result);
17+
```
18+
19+
Output
20+
```
21+
[5, 8, 9]
22+
```
23+
24+
> Pipeline execution is covered further in [Intermediate vs Terminal Operations](./G%20Intermediate%20Vs%20Terminal%20Operations.md).
25+
26+
---
27+
28+
<div align="right">
29+
30+
[How to Create a Stream](./C%20How%20To%20Create%20A%20Stream.md) →
31+
32+
</div>

src/test/java/com/github/streams/learn/concepts/D. Stream vs Collection.md renamed to src/test/java/com/github/streams/learn/concepts/F Stream Vs Collection.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,12 @@ Output
3030
<tr>
3131
<td style="text-align: left;">
3232

33-
← [Primitive Streams](./C.%20Primitive%20Streams.md)
33+
← [Primitive Streams](./D%20Primitive%20Streams.md)
3434

3535
</td>
3636
<td style="text-align: right;">
3737

38-
[Intermediate vs Terminal Operations](./E.%20Intermediate%20vs%20Terminal%20Operations.md) →
38+
[Intermediate vs Terminal Operations](./G%20Intermediate%20Vs%20Terminal%20Operations.md) →
3939

4040
</td>
4141
</tr>

src/test/java/com/github/streams/learn/concepts/E. Intermediate vs Terminal Operations.md renamed to src/test/java/com/github/streams/learn/concepts/G Intermediate Vs Terminal Operations.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,12 @@ Output
4242
<tr>
4343
<td style="text-align: left;">
4444

45-
← [Stream vs Collection](./D.%20Stream%20vs%20Collection.md)
45+
← [Stream vs Collection](./F%20Stream%20Vs%20Collection.md)
4646

4747
</td>
4848
<td style="text-align: right;">
4949

50-
[Lazy Evaluation](./F.%20Lazy%20Evaluation.md) →
50+
[Lazy Evaluation](./H%20Lazy%20Evaluation.md) →
5151

5252
</td>
5353
</tr>

src/test/java/com/github/streams/learn/concepts/F. Lazy Evaluation.md renamed to src/test/java/com/github/streams/learn/concepts/H Lazy Evaluation.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,12 @@ Streams are lazy. Most operations do not run when you write them. They run only
77
<tr>
88
<td style="text-align: left;">
99

10-
← [Intermediate vs Terminal Operations](./E.%20Intermediate%20vs%20Terminal%20Operations.md)
10+
← [Intermediate vs Terminal Operations](./G%20Intermediate%20Vs%20Terminal%20Operations.md)
1111

1212
</td>
1313
<td text-align="right">
1414

15-
[Single-Use Streams](./G.%20Single-Use%20Streams.md) →
15+
[Single-Use Streams](./I%20Single%20Use%20Streams.md) →
1616

1717
</td>
1818
</tr>

src/test/java/com/github/streams/learn/concepts/G. Single-Use Streams.md renamed to src/test/java/com/github/streams/learn/concepts/I Single Use Streams.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,12 @@ System.out.println(count);
3131
<tr>
3232
<td style="text-align: left;">
3333

34-
← [Lazy Evaluation](./F.%20Lazy%20Evaluation.md)
34+
← [Lazy Evaluation](./H%20Lazy%20Evaluation.md)
3535

3636
</td>
3737
<td style="text-align: right;">
3838

39-
[Optional Results](./H.%20Optional%20Results.md) →
39+
[Optional Results](./J%20Optional%20Results.md) →
4040

4141
</td>
4242
</tr>

0 commit comments

Comments
 (0)