Add Practice Exercise: etl (#321)

* add scaffold

* format tests

* input/h -> legacy

* Use Span inside dict

* fix test debug format

* add solution

* set instructions.append

* update config.json(s)

config.json

@@ -884,6 +884,14 @@
         "practices": [],
         "prerequisites": [],
         "difficulty": 5
+      },
+      {
+        "slug": "etl",
+        "name": "ETL",
+        "uuid": "b61157d4-6db8-4a52-a772-2e1037b3c071",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 3
       }
     ],
     "foregone": [

exercises/practice/etl/.docs/instructions.append.md

@@ -0,0 +1,5 @@
+# Instructions append
+
+Because it is not possible in Cairo to iterate over `Felt252Dict` keys, the tests will only be verifying that the expected letter keys have the correct values in the dictionary.
+
+The tests are configured to ignore all other keys that may be set in the resulting dictionary.

exercises/practice/etl/.docs/instructions.md

@@ -0,0 +1,27 @@
+# Instructions
+
+Your task is to change the data format of letters and their point values in the game.
+
+Currently, letters are stored in groups based on their score, in a one-to-many mapping.
+
+- 1 point: "A", "E", "I", "O", "U", "L", "N", "R", "S", "T",
+- 2 points: "D", "G",
+- 3 points: "B", "C", "M", "P",
+- 4 points: "F", "H", "V", "W", "Y",
+- 5 points: "K",
+- 8 points: "J", "X",
+- 10 points: "Q", "Z",
+
+This needs to be changed to store each individual letter with its score in a one-to-one mapping.
+
+- "a" is worth 1 point.
+- "b" is worth 3 points.
+- "c" is worth 3 points.
+- "d" is worth 2 points.
+- etc.
+
+As part of this change, the team has also decided to change the letters to be lower-case rather than upper-case.
+
+~~~~exercism/note
+If you want to look at how the data was previously structured and how it needs to change, take a look at the examples in the test suite.
+~~~~

exercises/practice/etl/.docs/introduction.md

@@ -0,0 +1,16 @@
+# Introduction
+
+You work for a company that makes an online multiplayer game called Lexiconia.
+
+To play the game, each player is given 13 letters, which they must rearrange to create words.
+Different letters have different point values, since it's easier to create words with some letters than others.
+
+The game was originally launched in English, but it is very popular, and now the company wants to expand to other languages as well.
+
+Different languages need to support different point values for letters.
+The point values are determined by how often letters are used, compared to other letters in that language.
+
+For example, the letter 'C' is quite common in English, and is only worth 3 points.
+But in Norwegian it's a very rare letter, and is worth 10 points.
+
+To make it easier to add new languages, your team needs to change the way letters and their point values are stored in the game.

exercises/practice/etl/.meta/config.json

@@ -0,0 +1,22 @@
+{
+  "authors": [
+    "0xNeshi"
+  ],
+  "files": {
+    "solution": [
+      "src/lib.cairo"
+    ],
+    "test": [
+      "tests/etl.cairo"
+    ],
+    "example": [
+      ".meta/example.cairo"
+    ],
+    "invalidator": [
+      "Scarb.toml"
+    ]
+  },
+  "blurb": "Change the data format for scoring a game to more easily add other languages.",
+  "source": "Based on an exercise by the JumpstartLab team for students at The Turing School of Software and Design.",
+  "source_url": "https://turing.edu"
+}

exercises/practice/etl/.meta/example.cairo

@@ -0,0 +1,22 @@
+use core::dict::Felt252Dict;
+use core::nullable::{match_nullable, FromNullableResult};
+
+pub fn transform(legacy: Felt252Dict<Nullable<Span<u8>>>) -> Felt252Dict<u32> {
+    let mut legacy = legacy;
+    let mut result: Felt252Dict<u32> = Default::default();
+    for point in 1..11_u32 {
+        let letters = legacy.get(point.into());
+        let letters = match match_nullable(letters) {
+            FromNullableResult::NotNull(v) => v.unbox(),
+            FromNullableResult::Null => array![].span(),
+        };
+        for letter in letters {
+            result.insert(lowercase(letter).into(), point);
+        }
+    };
+    result
+}
+
+fn lowercase(upper: @u8) -> u8 {
+    *upper + 32
+}

exercises/practice/etl/.meta/tests.toml

@@ -0,0 +1,22 @@
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
+
+[78a7a9f9-4490-4a47-8ee9-5a38bb47d28f]
+description = "single letter"
+
+[60dbd000-451d-44c7-bdbb-97c73ac1f497]
+description = "single score with multiple letters"
+
+[f5c5de0c-301f-4fdd-a0e5-df97d4214f54]
+description = "multiple scores with multiple letters"
+
+[5db8ea89-ecb4-4dcd-902f-2b418cc87b9d]
+description = "multiple scores with differing numbers of letters"

exercises/practice/etl/Scarb.toml

@@ -0,0 +1,7 @@
+[package]
+name = "etl"
+version = "0.1.0"
+edition = "2024_07"
+
+[dev-dependencies]
+cairo_test = "2.9.2"

exercises/practice/etl/src/lib.cairo

@@ -0,0 +1,5 @@
+use core::dict::Felt252Dict;
+
+pub fn transform(legacy: Felt252Dict<Nullable<Span<u8>>>) -> Felt252Dict<u32> {
+    panic!("implement `transform`")
+}

exercises/practice/etl/tests/etl.cairo

@@ -0,0 +1,155 @@
+use core::fmt::Formatter;
+use core::dict::Felt252Dict;
+
+#[test]
+fn transform_one_value() {
+    let legacy_data = input_from(array![(1, array!['A'])]);
+
+    let expected = expected_from(array![('a', 1)]);
+
+    assert_dicts_eq(expected, etl::transform(legacy_data));
+}
+
+#[test]
+#[ignore]
+fn transform_more_values() {
+    #[cairofmt::skip]
+    let legacy_data = input_from(array![
+        (1, array!['A', 'E', 'I', 'O', 'U']),
+    ]);
+    #[cairofmt::skip]
+    let expected = expected_from(array![
+        ('a', 1),
+        ('e', 1),
+        ('i', 1),
+        ('o', 1),
+        ('u', 1),
+    ]);
+
+    assert_dicts_eq(expected, etl::transform(legacy_data));
+}
+
+#[test]
+#[ignore]
+fn more_keys() {
+    #[cairofmt::skip]
+    let legacy_data = input_from(array![
+        (1, array!['A', 'E']),
+        (2, array!['D', 'G']),
+    ]);
+    #[cairofmt::skip]
+    let expected = expected_from(array![
+        ('a', 1),
+        ('e', 1),
+        ('d', 2),
+        ('g', 2),
+    ]);
+
+    assert_dicts_eq(expected, etl::transform(legacy_data));
+}
+
+#[test]
+#[ignore]
+fn full_dataset() {
+    let legacy_data = input_from(
+        array![
+            (1, array!['A', 'E', 'I', 'O', 'U', 'L', 'N', 'R', 'S', 'T']),
+            (2, array!['D', 'G']),
+            (3, array!['B', 'C', 'M', 'P']),
+            (4, array!['F', 'H', 'V', 'W', 'Y']),
+            (5, array!['K']),
+            (8, array!['J', 'X']),
+            (10, array!['Q', 'Z']),
+        ],
+    );
+
+    let expected = expected_from(
+        array![
+            ('a', 1),
+            ('b', 3),
+            ('c', 3),
+            ('d', 2),
+            ('e', 1),
+            ('f', 4),
+            ('g', 2),
+            ('h', 4),
+            ('i', 1),
+            ('j', 8),
+            ('k', 5),
+            ('l', 1),
+            ('m', 3),
+            ('n', 1),
+            ('o', 1),
+            ('p', 3),
+            ('q', 10),
+            ('r', 1),
+            ('s', 1),
+            ('t', 1),
+            ('u', 1),
+            ('v', 4),
+            ('w', 4),
+            ('x', 8),
+            ('y', 4),
+            ('z', 10),
+        ],
+    );
+
+    assert_dicts_eq(expected, etl::transform(legacy_data));
+}
+
+fn input_from(v: Array<(u32, Array<u8>)>) -> Felt252Dict<Nullable<Span<u8>>> {
+    let mut dict: Felt252Dict<Nullable<Span<u8>>> = Default::default();
+    for (num, letters) in v {
+        dict.insert(num.into(), NullableTrait::new(letters.span()));
+    };
+    dict
+}
+
+fn expected_from(v: Array<(u8, u32)>) -> Felt252Dict<u32> {
+    let mut dict: Felt252Dict<u32> = Default::default();
+    for (char, num) in v {
+        dict.insert(char.into(), num);
+    };
+    dict
+}
+
+
+fn assert_dicts_eq(expected: Felt252Dict<u32>, actual: Felt252Dict<u32>) {
+    let mut expected = expected;
+    let mut actual = actual;
+    let mut unequal = false;
+    for char in 'a'..('z' + 1_u8) {
+        if expected.get(char.into()) != actual.get(char.into()) {
+            unequal = true;
+            break;
+        }
+    };
+    if unequal {
+        let mut f: Formatter = Default::default();
+        writeln!(f, "\nexpected:").expect('write expected');
+        f = write_dict(f, expected);
+        writeln!(f, "actual:").expect('write expected');
+        f = write_dict(f, actual);
+        panic!("{}", f.buffer);
+    }
+}
+
+fn write_dict(mut f: Formatter, dict: Felt252Dict<u32>) -> Formatter {
+    let mut dict = dict;
+    write!(f, "{{").expect('should write {');
+    let mut empty = true;
+    for char in 'a'..('z' + 1_u8) {
+        let points = dict.get(char.into());
+        if points != 0 {
+            if empty {
+                empty = false;
+                writeln!(f, "").expect('should write empty char');
+            }
+            let mut letter = "";
+            letter.append_byte(char);
+            writeln!(f, "    \"{}\": {},", letter, points).expect('should write letter');
+        }
+    };
+    writeln!(f, "}}").expect('should write }');
+    f
+}