ENIB S4-PRG-Rust 02_Params - Passages de paramètres

{} Coûts relatifs des opérations

La comparaison des performances de différentes solutions reposera sur l'usage du type Benchmark fourni par le module s4.
Voici une descriptions des diverses étapes de sa mise en œuvre :

L'initialisation, avec un titre choisi librement, aura cette forme
```
let bm = s4::Benchmark::new("starting_occurrence");
```
Chacune des mesures à effectuer est réalisée de cette façon (ceci aura lieu plusieurs fois en faisant varier le contenu)
```
bm.record("this solution", 2.0, |t| {
    // ... prepare parameters if needed ...
    s4::bm_call!(t, my_function(param1, param2, ...));
});
```
Le titre et la durée en secondes de la mesure sont choisis librement.
L'outil bm répète le traitement représenté par la closure
```
|t| { ... }
```
autant de fois que nécessaire pour que le temps total de mesure atteigne au moins la durée choisie.
La seule partie mesurée est l'appel de fonction✍
Bien entendu, my_function(), param1, param2... n'ont aucune signification ici.
Il faudra les remplacer par le traitement que nous souhaitons mesurer.
inscrit dans la macro s4::bm_call!(t, ... )✍
Si la forme du traitement à mesurer tient en plusieurs étapes, il est possible de l'exprimer comme ceci :
```
bm.record("another solution", 2.0, |t| {
    // ... prepare parameters if needed ...
    t.add(|| {
        s4::bm_call!(my_function_a(param_a1, param_a2, ...));
        s4::bm_call!(my_function_b(param_b1, param_b2, ...));
    });
});
```
Tout ce qui figure dans
```
t.add(|| { ... })
```
est pris en compte dans la mesure.
L'usage de
```
s4::bm_call!( ... )
```
sert à éviter que le compilateur n'élimine des opérations qu'il juge inutiles lorsqu'elles sont artificiellement répétées en boucle par l'outil bm (voir
```
rustup doc --std 'core::hint::black_box'
```
).
; une préparation des paramètres peut précéder, si nécessaire, sans être comptabilisée dans la mesure.
Un affichage synthétique permettant de comparer l'ensemble des mesures effectuées précédemment est simplement obtenu ainsi
```
println!("{}", bm);
```

Comme prétexte à l'expérimentation que nous envisageons, introduisez dans votre code cette nouvelle fonction.

fn starting_occurrence(
    word_occurrences: Vec<(String, u64)>,
    character: char,
) -> u64 {
    word_occurrences
        .iter()
        .filter_map(|(word, occurrence)| {
            word.chars()
                .next()
                .filter(|c| *c == character)
                .and(Some(occurrence))
        })
        .sum()
}

Les détails de son fonctionnement interne importent peu pour l'instant.
Elle exploite une séquence de paires “mot”—“nombre d'occurrences de ce mot” fournie comme son premier paramètre✍.
Son rôle est de déterminer le nombre d'occurrences des mots qui commencent par le caractère indiqué en second paramètre.

Dans la fonction chapter_2::section_1(), avec un l'outil s4::Benchmark, nous mesurerons et comparerons trois invocations différentes✍ de la fonction starting_occurrence().
Dans les trois cas, la même lettre ('z' par exemple) sera choisie comme second paramètre.
Ces trois mesures diffèrent seulement dans la manière de fournir le premier paramètre de la fonction mesurée :

La lecture des données depuis un fichier :
- La première mesure consiste à directement appeler s4::load_word_occurrences()✍
  Cette fonction utilitaire lit le fichier count_big.txt déjà fourni dans le projet, afin d'obtenir les occurrences de 29136 mots en langue Anglaise.
  Il a été téléchargé depuis https://norvig.com/ngrams/.
  comme premier paramètre.
- Ce choix signifie que le fichier sera relu à chaque invocation de la fonction starting_occurrence(), et cela sera pris en compte dans la mesure.
Le clonage depuis des données déjà préparées :
- Avant la seconde mesure il faudra charger une fois pour toutes le résultat de s4::load_word_occurrences() dans une variable (avant le second appel à bm.record()).
- Lors de la mesure, le premier paramètre de la fonction starting_occurrence() sera directement le résultat de .clone() sur les données préalablement chargées.
- Ce choix signifie que l'opération de clonage aura lieu à chaque invocation de la fonction starting_occurrence(), et cela sera pris en compte dans la mesure.
Le déplacement (la consommation) de données déjà préparées :
- Pour la troisième mesure, il faudra déplacer l'appel à .clone() juste avant s4::bm_call!(t, ...) afin qu'il serve à préparer une variable qui sera le premier paramètre de la fonction starting_occurrence().
- Ce choix signifie que l'opération de clonage ne sera désormais plus prise en compte dans la mesure ; seul le déplacement de cette variable vers le paramètre le sera.

Il reste alors à afficher la variable bm pour rendre visible le bilan de ces mesures.

En exécutant ce programme avec la commande habituelle cargo run 2 1, nous constatons que le type s4::Benchmark nous avertit du fait que les mesures de performances ne seront pas significatives.
En effet, par défaut le code exécutable généré n'est pas optimisé et convient aux opérations de mise-au-point.
En relançant avec la commande cargo run --release 2 1, le code exécutable généré sera optimisé et les mesures de performances seront alors significatives.

Observez attentivement les performances reportées.
Pour chaque mesure, nous y trouvons :

un pourcentage d'efficacité (100.0% pour la solution la plus rapide),
une durée moyenne constatée pour chaque invocation,
des propriétés quant à la fiabilité et la variabilités des durées mesurées.

Faites le lien entre ces observations et ce que vous savez désormais du déplacement et du clonage.
Comment se situe l'exploitation d'un fichier par rapport à ces opérations ?

Au-delà du langage de programmation utilisé, ces considérations en termes de chargement et de duplication des données seront à garder à l'esprit dans toutes les réalisations futures.

{} Passages par références partagées (non-mutables)

Tout comme cela avait été fait au début de cette étape, recréez dans la fonction chapter_2::section_2() les variables u, f, t et v, puis utilisez s4::show_mem!() pour en décrire le placement en mémoire.

De la même façon qu'à cette étape nous avions réalisé une fonction show_params() attendant des paramètres de types variés, introduisez maintenant une fonction show_ref_params() attendant des paramètres similaires (nommés également pu, pf, pt et pv), mais passés par références partagées (non-mutables).
Cette fonction décrira également le placement en mémoire :

de ses paramètres (des références) (s4::show_mem!("pu", pu); s4::show_mem!("pf", pf); ...),
de ce que ces références désignent (s4::show_mem!("*pu", *pu); s4::show_mem!("*pf", *pf); ...).

Elle sera bien entendu appelée en passant des références sur les variables u, f, t et v préalablement préparées.

Observez attentivement les placements en mémoire reportés.

Comment interpréter les tailles en octets de pu, pf, pt et pv ?
Les variables pu, pf, pt et pv sont elles éloignées des variables u, f, t et v ?
Réalisez un dessin similaire à ce qui avait été réalisé à cette étape, en distinguant la pile (stack) et le tas (heap).

Activité complémentaire :

Complétez la démarche avec une utilisation similaire d'une donnée de type String.

Introduisez maintenant une fonction starting_occurrence_ref() qui n'est rien d'autre qu'une copie de starting_occurrence() mais dont le premier paramètre est passé par référence (

&Vec<...>

).
Complétez alors les mesures de performances effectuées à cette étape par un nouveau cas qui concerne cette nouvelle fonction.

Comment se situe cette nouvelle mesure de performances par rapport aux précédentes ?

Qu'est-ce qui pourrait expliquer un tel écart✍ ?

La fonction starting_occurrence() avait-elle une bonne raison de prendre possession d'une valeur, qui sera détruite à la fin, plutôt que d'y faire référence, sans décider de sa durée de vie ?

Ces considérations en termes de passage par valeur ou référence seront à garder à l'esprit dans toutes les réalisations futures.

{} Passages par slices partagées (non-mutables)

Recréez une nouvelle fois, comme cela avait été fait à l'étape précédente, dans la fonction chapter_2::section_3(), les deux variables t et v, puis utilisez s4::show_mem!() pour décrire le placement en mémoire de t, v, t[0] et v[0].

Après avoir étudié cette section, réalisez une fonction show_slice_params() attendant deux paramètres pt et pv.
Ces deux paramètres seront des slices qui permettront de désigner respectivement le contenu des variables t et v préparées précédemment.
Pour chacun des deux paramètres :

utilisez s4::show_mem!() pour en décrire le placement en mémoire,
affichez ce qu'indiquent leurs fonctions .as_ptr() et .len().

Cette fonction sera bien entendu appelée en passant une slice qui désigne le contenu de la variable t et une autre slice qui désigne le contenu de la variable v.

Observez attentivement les placements en mémoire reportés et les informations indiquées.

En déduire les informations qui constituent fondamentalement une slice.
Réalisez un dessin similaire à ce qui avait été réalisé à cette étape, en distinguant la pile (stack) et le tas (heap).
Est-il possible d'intervertir les slices issues de t et de v lors de l'appel à show_slice_params() ?
(Qu'en est-il avec show_ref_params() ?)
Un slice issue de t ou de v doit-elle nécessairement couvrir l'ensemble des données d'origine ? (voir la fin de cette section)

En déduire l'intérêt de réaliser une fonction travaillant sur une slice, plutôt que spécifiquement sur un tableau ou un vector ou tout autre moyen de stocker des éléments contigus.

Activité complémentaire :

Complétez la démarche avec une utilisation similaire d'une donnée de type String et une string-slice.
Une chaîne littérale est-elle utilisable avec une string-slice ?

Introduisez maintenant une fonction starting_occurrence_slice() qui n'est rien d'autre qu'une copie de starting_occurrence() mais dont le premier paramètre est passé comme une slice (

&[...]

).
Complétez alors les mesures de performances effectuées à cette étape par un nouveau cas qui concerne cette nouvelle fonction.

Comment se situe cette nouvelle mesure de performances par rapport aux précédentes ?
La fonction starting_occurrence_ref() offrait-elle un quelconque avantage sur la fonction starting_occurrence_slice(), que ce soit en termes de facilité d'usage ou de performance ?

Ces considérations en termes de passage de multiples éléments contigus par slice seront à garder à l'esprit dans toutes les réalisations futures.

{} Passages par références et slices exclusives (mutables)

Jusqu'alors, les fonctions réalisées ne faisaient que consulter les données transmises✍.
Nous envisageons dorénavant des fonctions dont le rôle serait de modifier les données auxquelles on leur donne accès.

Introduisez maintenant une fonction extend_arithmetic_sequence().
Elle attend en paramètre une séquence de réels (f64) mémorisés dans un vector.
Son algorithme doit être le suivant :

déterminer n, le nombre d'éléments de la séquence
Si n est supérieur ou égal à 2
- déterminer v1, l'élément à la position n - 1 dans la séquence
- déterminer v2, l'élément à la position n - 2 dans la séquence
- ajouter à la séquence la valeur de v1 + (v1 -v2)✍
  Nous complétons la séquence en produisant toujours le même écart entre les deux dernier éléments ; il s'agit donc d'une suite arithmétique.

Complétez la fonction chapter_2::section_4() afin qu'elle effectue ces opérations :

créer un vector contenant la séquence de réels 10.0, 12.5, 15.0,
afficher cette séquence,
utiliser la fonction extend_arithmetic_sequence() sur cette séquence,
afficher à nouveau cette séquence.

Le compilateur ne devrait pas vous laisser faire cela...

Quel est le problème fondamental rencontré ici ?
Un passage par référence partagée (non-mutable), comme nous l'effectuions à cette étape, améliore-t-il la situation ?

Envisagez alors un passage par référence exclusive (mutable).

L'effet est-il enfin conforme à nos attentes ?
En déduire l'utilité d'un tel passage par référence exclusive (mutable).

Introduisez maintenant une fonction invert_values().
Son rôle est de remplacer chacun des réels (f64) d'une séquence passée en paramètre par son inverse (x devient 1.0/x).
À propos du choix du mode de passage du paramètre qui convient le mieux au rôle de cette fonction, posez-vous tout d'abord ces questions :

Est-il raisonnable que la séquence d'origine devienne inutilisable suite à l'appel de cette fonction ?
La séquence de réels passée en paramètre n'est-elle que consultée ?
Est-il important pour le traitement envisagé de savoir si cette séquence de réels est stockée dans un vector, un tableau, ou tout autre procédé disposant les réels de manière contiguë ?

Vous devriez alors vous tourner vers une slice exclusive (mutable).
Complétez votre programme pour utiliser cette fonction sur le vector qui a été précédemment étendu, puis en l'affichant à nouveau.

Aurait-il été possible d'utiliser une telle slice exclusive (mutable), à la place d'une référence exclusive (mutable) sur un vector, pour le paramètre de la fonction extend_arithmetic_sequence() ?
En déduire la règle à suivre pour effectuer un tel choix.

Activité complémentaire :

Vérifiez que vous pouvez également utiliser la fonction invert_values() sur un tableau (pas un vector) contenant des réels de votre choix.
Vérifiez encore que cette fonction est utilisable sur un sous-ensemble du tableau ou du vector.

{} Définition d'un type structuré

Dans tout ce qui précède, nous n'avons utilisé que des types de base du langage, ainsi que des types élaborés très courants de la bibliothèque standard.
Il s'agit maintenant d'inventer notre propre type pour matérialiser une notion bien identifiée qui pourra être transmise comme un tout à divers traitements.

Comme prétexte ici, nous utiliserons la notion d'équation de second degré.
Introduisez alors un type structuré SecondDegree composé de ces trois membres :

coefs : un tableau de trois réels (f64) représentant les coefficients dans l'ordre des degrés décroissants✍
L'équation a·x² + b·x + c = 0 est représentée par le tableau [a, b, c].
.
delta : un réel (f64) représentant le discriminant de l'équation,
solutions : un tableau de deux réels optionnels (
```
Option<f64>
```
) représentant les éventuelles solutions de l'équation.

Dans la fonction chapter_2::section_5(), créez une telle structure avec les coefficients 2.0, 8.0 et 6.0.
Le discriminant sera pour l'instant initialisé à 0.0 et les deux solutions à None.
Provoquez l'affichage de débogage de cette structure.

Bien entendu, pour l'instant, les deux derniers membres de la structure n'ont pas encore de valeurs significatives.
Ajoutez alors une fonction solve_second_degree() dont le rôle est de mettre à jour les membres delta et solutions✍ d'une structure SecondDegree passée en paramètre, en fonction de son membre coefs✍.

Quel est le mode de passage de paramètre adapté à notre intention ?
Affichez alors le nouvel état de la structure après l'appel à cette fonction afin de constater que le discriminant vaut 16.0 et que les deux solutions sont -3.0 et -1.0.
Répétez l'opération lorsque le dernier coefficient vaut 8.0 puis 10.0✍
Vous devriez constater qu'il n'y a d'abord une seule solution (discriminant nul) en -2.0, puis plus aucune solution (discriminant négatif).
.

Il est également utile d'accompagner notre type avec une nouvelle fonction compute_second_degree() dont le rôle est de fournir comme résultat la valeur de ce polynôme de second degré pour une valeur de x fournie✍.

Quel est le type attendu pour la valeur de retour de cette fonction ?
Pour les deux paramètres, quels sont les types et modes de passage adaptés à notre intention ?
Pour chaque valeur du dernier coefficient (6.0 puis 8.0 et enfin 10.0, réalisez une boucle qui affiche lisiblement le résultat de cette évaluation pour des réels de -4.0 à 0.0 par pas de 0.5✍
Il s'agit d'une boucle de 9 itérations au cours de laquelle vous devriez constater :
- les deux valeurs nulles aux passages par -3.0 et -1.0 lorsque le dernier coefficient vaut 6.0,
- une seule valeur nulle au passage par -2.0 lorsque le dernier coefficient vaut 8.0,
- aucune valeur nulle lorsque le dernier coefficient vaut 10.0.
N'hésitez pas à visualiser les polynômes en question avec votre calculette, un outil en ligne ou bien un outil comme Gnuplot sous Linux.
```
gnuplot -p -e 'set term x11; plot [-4:0] 0, 2*x**2+8*x+6, 2*x**2+8*x+8, 2*x**2+8*x+10'
```
.

{} Encapsulation d'un type élaboré

Le type structuré réalisé à l'étape précédente, accompagné des deux fonctions qui l'exploitent, peut certes se montrer utile pour quelques problèmes calculatoires, mais il est extrêmement inconfortable et maladroit en termes d'utilisation !

Est-il cohérent de devoir fournir des valeurs initiales pour les membres delta et solutions alors qu'il existe une fonction qui se charge justement de les mettre à jour ?
Une fois l'équation résolue, si nous changeons les coefficients, les solutions restent-elles valides ?
Qu'est-ce qui empêche de modifier le discriminant ou les solutions d'une manière totalement fantaisiste ?
Dans ces conditions, si nous fournissons une telle structure à un traitement calculatoire, quelles sont les garanties quant à la validité des informations qu'elle contient ?
De manière similaire, serait-il raisonnable de pouvoir changer arbitrairement l'information de longueur par exemple, sur les types standards Vec ou String, sans ne rien changer à l'ensemble des données mémorisées et à la quantité de mémoire allouée dynamiquement ?

⟶L'encapsulation vise à garantir la cohérence de l'état interne (les invariants) d'un type que nous réalisons.

Puisque l'encapsulation est contrôlée au niveau des modules, nous réaliserons le module equation✍.
Placez-y, par copier/coller, une nouvelle version du type SecondDegree (sans les deux fonctions qui l'accompagnaient précédemment).

Dans la fonction chapter_2::section_6(), essayez d'initialiser une donnée de type equation::SecondDegree selon le même procédé qu'à l'étape précédente, c'est à dire en initialisant chacun des membres.
Quelle est la nature de l'erreur reportée dans ce cas ?

Qualifiez la définition du type SecondDegree (dans equation) avec le mot-clef pub (avant struct).

Qu'est-ce que cela change ?
Quelle similarité constate-t-on avec l'erreur précédente ?
Devrait-on faire de même pour les membres de la structure ?

Ajoutons alors (toujours dans equation) une implémentation à notre structure.
Placez-y dans un premier temps une fonction nommée new(), qualifiée de pub servant à initialiser une telle structure.

Le type de retour de cette fonction est Self puisque son propos est de fournir une donnée ayant le type auquel correspond l'implémentation.
Elle attend uniquement trois paramètre réels qui serviront à initialiser le membre coefs de la structure en question.
À partir des ces coefficients, elle doit déterminer le discriminant et les éventuelles solutions afin d'initialiser complètement la structure qui sera renvoyée.

Dans la fonction chapter_2::section_6(), faites maintenant usage de la fonction equation::SecondDegree::new() afin d'obtenir une structure que vous afficherez✍.

Est-il possible d'obtenir une structure dont les membres delta et solutions ne sont pas en phase avec son membre coefs ?
Est-il toujours possible de modifier directement les membres de la structure ainsi obtenue ?

En l'état, notre structure ne sert pas à grand chose puisque nous ne pouvons que l'afficher.
Ajoutez à l'implémentation trois fonctions publiques qui ne serviront qu'à consulter l'état d'une donnée de ce type :

choisissez la forme du paramètre self qui correspond à ces usages,
coefs() renverra une référence partagée (non-mutable) sur le membre coefs,
delta() renverra la valeur du membre delta,
solutions() renverra une référence partagée (non-mutable) sur le membre solutions.

Complétez alors la fonction chapter_2::section_6() pour afficher lisiblement ce que ces fonctions renvoient.
Désormais, notre équation du second degré est utilisable a minima : nous pourrions exploiter son discriminant et ses solutions dans un calcul plus élaboré.

Activité complémentaire :

Complétez l'implémentation de SecondDegree avec une fonction publique compute() qui évalue le polynôme du second degré pour une valeur de x fournie✍
Son rôle est similaire à la fonction compute_second_degree() de l'étape précédente.
; il faut à nouveau déterminer avec soin le mode de passage de self.
Testez cette fonction, de manière similaire à l'étape précédente, de façon à mettre en évidence les passages par les solutions.

La cohérence de notre type est jusqu'alors facile à assurer puisque tout est déterminé à l'initialisation et il n'y a aucun moyen de modifier la structure existante ; c'est assez restrictif à l'usage.
Pour illustrer simplement la possibilité de modifier la structure, ajoutez à l'implémentation une fonction translate_y() :

On lui fournit un réel qu'elle ajoutera au dernier des trois coefficients.
Elle recalcule alors le discriminant et les éventuelles solutions.
Il faut déterminer avec soin le mode de passage de self qui correspond à notre intention (modifier une structure existante).

Complétez alors la fonction chapter_2::section_6() pour provoquer plusieurs translations verticales de 2.0, en affichant à chaque fois les propriétés de la structure, de façon à mettre en évidence l'actualisation des calculs (deux solutions, puis une, puis aucune).
Notre type offre maintenant un peu plus de services, notamment la possibilité de modifier son état, tout en restant toujours cohérent vis-à-vis de la signification que nous lui donnons.

Activité complémentaire :

Remarquez que la fonction new() et la fonction translate_y() ont une bonne partie de leur code qui est redondante ; c'est en général une très mauvaise pratique, qui complique la maintenance du code.
Complétez l'implémentation par une fonction solve() qui n'est pas publique✍
Elle ne sera donc pas utilisable depuis l'extérieur du module.
Elle ne sert qu'à un usage interne : factoriser le code de l'implémentation.
.
Modifiez le code des fonctions new() et translate_y() afin qu'elles remplacent les calcul redondants par des appels à la fonction interne solve().

Code source résultant

Si chaque étape a été respectée scrupuleusement, vous devez obtenir un fichier de code source semblable à celui-ci :

Fichier chapter_2.rs✎

Contenu du fichier chapter_2.rs

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#[allow(unused_imports)]
use crate::s4;

pub const SECTIONS: &[fn()] = &[
    section_1, section_2, section_3, section_4, section_5, section_6,
];

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

fn starting_occurrence(
    word_occurrences: Vec<(String, u64)>,
    character: char,
) -> u64 {
    word_occurrences
        .iter()
        .filter_map(|(word, occurrence)| {
            word.chars()
                .next()
                .filter(|c| *c == character)
                .and(Some(occurrence))
        })
        .sum()
}

fn section_1() {
    println!("\n~~~~ chapter 2, section 1 ~~~~");
    let bm = s4::Benchmark::new("starting_occurrence");
    bm.record("load", 2.0, |t| {
        s4::bm_call!(
            t,
            starting_occurrence(s4::load_word_occurrences(), 'z')
        );
    });
    let word_occurrences = s4::load_word_occurrences();
    bm.record("clone", 2.0, |t| {
        s4::bm_call!(t, starting_occurrence(word_occurrences.clone(), 'z'));
    });
    bm.record("move", 2.0, |t| {
        let word_occurrences = word_occurrences.clone(); // not measured
        s4::bm_call!(t, starting_occurrence(word_occurrences, 'z'));
    });
    // section 2
    bm.record("ref", 2.0, |t| {
        s4::bm_call!(t, starting_occurrence_ref(&word_occurrences, 'z'));
    });
    bm.record("ref+drop", 2.0, |t| {
        let word_occurrences = word_occurrences.clone(); // not measured
        t.add(|| {
            // these two lines of code are considered in the measure
            s4::bm_call!(starting_occurrence_ref(&word_occurrences, 'z'));
            drop(word_occurrences); // free allocated resources
        });
    });
    // section 3
    bm.record("slice", 2.0, |t| {
        s4::bm_call!(
            t,
            starting_occurrence_slice(word_occurrences.as_slice(), 'z')
        );
    });
    println!("{}", bm);
}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

fn show_ref_params(
    pu: &u32,
    pf: &f64,
    pt: &[u16; 3],
    pv: &Vec<u16>,
    ps: &String,
) {
    s4::show_mem!(" pu", pu);
    s4::show_mem!(" pf", pf);
    s4::show_mem!(" pt", pt);
    s4::show_mem!(" pv", pv);
    s4::show_mem!(" ps", ps);
    s4::show_mem!("*pu", *pu);
    s4::show_mem!("*pf", *pf);
    s4::show_mem!("*pt", *pt);
    s4::show_mem!("*pv", *pv);
    s4::show_mem!("*ps", *ps);
}

#[allow(clippy::ptr_arg)]
fn starting_occurrence_ref(
    word_occurrences: &Vec<(String, u64)>,
    character: char,
) -> u64 {
    word_occurrences
        .iter()
        .filter_map(|(word, occurrence)| {
            word.chars()
                .next()
                .filter(|c| *c == character)
                .and(Some(occurrence))
        })
        .sum()
}

fn section_2() {
    println!("\n~~~~ chapter 2, section 2 ~~~~");
    let u = 98765_u32;
    let f = 12.34_f64;
    let t = [99_u16, 98, 97];
    let v = vec![88_u16, 87, 86];
    let s = "Short".to_owned();
    s4::show_mem!("   u", u);
    s4::show_mem!("   f", f);
    s4::show_mem!("   t", t);
    s4::show_mem!("   v", v);
    s4::show_mem!("   s", s);
    s4::show_mem!("t[0]", t[0]);
    s4::show_mem!("v[0]", v[0]);
    s4::show_mem!("s[0]", s.as_bytes()[0]);
    println!("~~~~~~~~");
    show_ref_params(&u, &f, &t, &v, &s);
}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

fn show_slice_params(
    pt: &[u16],
    pv: &[u16],
    ps: &str,
) {
    s4::show_mem!("  st", pt);
    println!("      ({:?}, {})", pt.as_ptr(), pt.len());
    s4::show_mem!("  sv", pv);
    println!("      ({:?}, {})", pv.as_ptr(), pv.len());
    s4::show_mem!("  ss", ps);
    println!("      ({:?}, {})", ps.as_ptr(), ps.len());
}

fn starting_occurrence_slice(
    word_occurrences: &[(String, u64)],
    character: char,
) -> u64 {
    word_occurrences
        .iter()
        .filter_map(|(word, occurrence)| {
            word.chars()
                .next()
                .filter(|c| *c == character)
                .and(Some(occurrence))
        })
        .sum()
}

fn section_3() {
    println!("\n~~~~ chapter 2, section 3 ~~~~");
    let t = [99_u16, 98, 97];
    let v = vec![88_u16, 87, 86];
    let s = "Short".to_owned();
    s4::show_mem!("   t", t);
    s4::show_mem!("   v", v);
    s4::show_mem!("   s", s);
    s4::show_mem!("t[0]", t[0]);
    s4::show_mem!("v[0]", v[0]);
    s4::show_mem!("s[0]", s.as_bytes()[0]);
    println!("~~~~~~~~");
    show_slice_params(t.as_slice(), v.as_slice(), s.as_str());
    println!("~~~~~~~~ changing parameters");
    show_slice_params(v.as_slice(), t.as_slice(), "literal string!");
    println!("~~~~~~~~ partial slices");
    show_slice_params(&v[1..3], &v[0..2], &s[1..4]);
}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// fn extend_arithmetic_sequence(mut seq: Vec<f64>) {
fn extend_arithmetic_sequence(seq: &mut Vec<f64>) {
    let n = seq.len();
    if n >= 2 {
        let v1 = seq[n - 1];
        let v2 = seq[n - 2];
        seq.push(v1 + (v1 - v2));
    }
}

fn invert_values(values: &mut [f64]) {
    for v in values.iter_mut() {
        *v = 1.0 / *v;
    }
}

fn section_4() {
    println!("\n~~~~ chapter 2, section 4 ~~~~");
    let mut v = vec![10.0, 12.5, 15.0];
    println!("initial v: {:?}", v);
    // extend_arithmetic_sequence(v);
    extend_arithmetic_sequence(&mut v);
    println!("extended v: {:?}", v);
    invert_values(v.as_mut_slice());
    println!("inverted v: {:?}", v);
    let mut t = [2.0, 4.0, 8.0, 16.0];
    println!("initial t: {:?}", t);
    invert_values(t.as_mut_slice());
    println!("inverted t: {:?}", t);
    invert_values(&mut t[2..4]);
    println!("partially inverted t: {:?}", t);
}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#[derive(Debug, Clone)]
struct SecondDegree {
    coefs: [f64; 3],
    delta: f64,
    solutions: [Option<f64>; 2],
}

fn solve_second_degree(sd: &mut SecondDegree) {
    let [a, b, c] = sd.coefs;
    sd.delta = b * b - 4.0 * a * c;
    sd.solutions[0] = if sd.delta >= 0.0 {
        Some((-b - sd.delta.sqrt()) / (2.0 * a))
    } else {
        None
    };
    sd.solutions[1] = if sd.delta > 0.0 {
        Some((-b + sd.delta.sqrt()) / (2.0 * a))
    } else {
        None
    };
}

fn compute_second_degree(
    sd: &SecondDegree,
    x: f64,
) -> f64 {
    let [a, b, c] = sd.coefs;
    (a * x + b) * x + c
}

fn section_5() {
    println!("\n~~~~ chapter 2, section 5 ~~~~");
    let mut sd = SecondDegree {
        coefs: [2.0, 8.0, 6.0],
        delta: 0.0,
        solutions: [None, None],
    };
    println!("{:?}", sd);
    for _ in 0..3 {
        solve_second_degree(&mut sd);
        println!("{:?} ~~> {} {:?}", sd.coefs, sd.delta, sd.solutions);
        for i in 0..9 {
            let x = (i as f64) * 0.5 - 4.0;
            println!("{} ~~> {}", x, compute_second_degree(&sd, x));
        }
        sd.coefs[2] += 2.0;
    }
    println!("{:?}", sd);
}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

mod equation {
    #[derive(Debug, Clone)]
    pub struct SecondDegree {
        coefs: [f64; 3],
        delta: f64,
        solutions: [Option<f64>; 2],
    }

    impl SecondDegree {
        pub fn new(
            a: f64,
            b: f64,
            c: f64,
        ) -> Self {
            if false {
                // initial version, without translate_x() neither solve()
                let delta = b * b - 4.0 * a * c;
                let solutions = [
                    if delta >= 0.0 {
                        Some((-b - delta.sqrt()) / (2.0 * a))
                    } else {
                        None
                    },
                    if delta > 0.0 {
                        Some((-b + delta.sqrt()) / (2.0 * a))
                    } else {
                        None
                    },
                ];
                Self {
                    coefs: [a, b, c],
                    delta,
                    solutions,
                }
            } else {
                // rely on private function solve()
                // instead of duplicating the code
                let mut sd = Self {
                    coefs: [a, b, c],
                    delta: 0.0,
                    solutions: [None, None],
                };
                sd.solve();
                sd
            }
        }

        pub fn coefs(&self) -> &[f64; 3] {
            &self.coefs
        }

        pub fn delta(&self) -> f64 {
            self.delta
        }

        pub fn solutions(&self) -> &[Option<f64>; 2] {
            &self.solutions
        }

        pub fn compute(
            &self,
            x: f64,
        ) -> f64 {
            let [a, b, c] = self.coefs;
            (a * x + b) * x + c
        }

        pub fn translate_y(
            &mut self,
            dy: f64,
        ) {
            self.coefs[2] += dy;
            self.solve();
        }

        fn solve(&mut self) {
            let [a, b, c] = self.coefs;
            self.delta = b * b - 4.0 * a * c;
            self.solutions[0] = if self.delta >= 0.0 {
                Some((-b - self.delta.sqrt()) / (2.0 * a))
            } else {
                None
            };
            self.solutions[1] = if self.delta > 0.0 {
                Some((-b + self.delta.sqrt()) / (2.0 * a))
            } else {
                None
            };
        }
    }
}

fn section_6() {
    println!("\n~~~~ chapter 2, section 6 ~~~~");
    let mut sd = equation::SecondDegree::new(2.0, 8.0, 6.0);
    println!("{:?}", sd);
    for _ in 0..3 {
        println!("{:?} ~~> {} {:?}", sd.coefs(), sd.delta(), sd.solutions());
        for i in 0..9 {
            let x = (i as f64) * 0.5 - 4.0;
            println!("{} ~~> {}", x, sd.compute(x));
        }
        sd.translate_y(2.0);
    }
    println!("{:?}", sd);
}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

À ne consulter qu'après avoir tenté de réaliser un exercice !