Add ProgressBar::visual_index and clarify meaning of ProgressBar::index.

src/multi.rs

@@ -416,12 +416,10 @@ impl MultiState {
                 self.ordering.insert(pos, idx);
             }
             InsertLocation::After(after_idx) => {
-                let pos = self.ordering.iter().position(|i| *i == after_idx).unwrap();
-                self.ordering.insert(pos + 1, idx);
+                self.ordering.insert(self.visual_index(after_idx) + 1, idx);
             }
             InsertLocation::Before(before_idx) => {
-                let pos = self.ordering.iter().position(|i| *i == before_idx).unwrap();
-                self.ordering.insert(pos, idx);
+                self.ordering.insert(self.visual_index(before_idx), idx);
             }
         }
 
@@ -465,6 +463,14 @@ impl MultiState {
     fn len(&self) -> usize {
         self.members.len() - self.free_set.len()
     }
+
+    /// Map from opaque index to position on screen.
+    pub(crate) fn visual_index(&self, opaque_index: usize) -> usize {
+        self.ordering
+            .iter()
+            .position(|v| *v == opaque_index)
+            .expect("no such member")
+    }
 }
 
 #[derive(Default)]

src/progress_bar.rs

@@ -633,11 +633,26 @@ impl ProgressBar {
         self.state().tab_width
     }
 
-    /// Index in the `MultiState`
+    /// Opaque index in the `MultiState`
+    ///
+    /// This value is an implementation detail and does not necessarily correspond to visual
+    /// position on the screen.
+    ///
+    /// It is an index into `MultiState::members`, which is not in any particular order (due to
+    /// reclaiming of indices from the `MultiState::free_set`).
     pub(crate) fn index(&self) -> Option<usize> {
         self.state().draw_target.remote().map(|(_, idx)| idx)
     }
 
+    /// If this [`ProgressBar`] is a member of a [`MultiProgress`](crate::MultiProgress), then return visual position
+    /// on screen. Otherwise, `None`.
+    pub fn visual_index(&self) -> Option<usize> {
+        self.state()
+            .draw_target
+            .remote()
+            .map(|(remote, idx)| remote.read().unwrap().visual_index(idx))
+    }
+
     /// Current message
     pub fn message(&self) -> String {
         self.state().state.message.expanded().to_string()