Skip to content

Commit f7818fc

Browse files
molpopgenmolpopgen
authored
refactor: deprecate NodeTable::flags_array_mut and NodeTable::time_array_mut (#405)
1 parent 7ed2b9f commit f7818fc

File tree

1 file changed

+110
-110
lines changed

1 file changed

+110
-110
lines changed

‎src/node_table.rs

Lines changed: 110 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -229,82 +229,7 @@ impl NodeTable {
229229
)
230230
}
231231

232-
/// Mutable access to node flags.
233-
///
234-
/// # Examples
235-
///
236-
///
237-
/// ```
238-
/// # use tskit::prelude::*;
239-
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
240-
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
241-
/// let flags = tables.nodes_mut().flags_array_mut();
242-
/// for flag in flags {
243-
/// // Can do something...
244-
/// # assert!(flag.is_sample());
245-
/// }
246-
/// ```
247-
///
248-
/// ```
249-
/// # use tskit::prelude::*;
250-
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
251-
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
252-
/// for flag in tables.nodes_mut().flags_array_mut() {
253-
/// # assert!(flag.is_sample());
254-
/// }
255-
/// ```
256-
///
257-
/// The returned slice is *mutable*, allowing one to do things like
258-
/// clear the sample status of all nodes:
259-
///
260-
/// A copy of the flags can be obtained by collecting results into `Vec`:
261-
///
262-
/// ```
263-
/// # use tskit::prelude::*;
264-
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
265-
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
266-
/// for flag in tables.nodes_mut().flags_array_mut() {
267-
/// flag.remove(tskit::NodeFlags::IS_SAMPLE);
268-
/// }
269-
/// assert!(!tables.nodes_mut().flags_array_mut().iter().any(|f| f.is_sample()));
270-
/// assert!(tables.nodes().samples_as_vector().is_empty());
271-
/// ```
272-
///
273-
/// ```
274-
/// # use tskit::prelude::*;
275-
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
276-
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
277-
/// let flags = tables.nodes_mut().flags_array_mut().to_vec();
278-
/// # assert!(flags.iter().all(|f| f.is_sample()));
279-
/// ```
280-
///
281-
/// ## Standalone tables
282-
///
283-
/// The ownership semantics differ when tables are not part of a
284-
/// table collection:
285-
///
286-
/// ```
287-
/// let mut nodes = tskit::OwnedNodeTable::default();
288-
/// assert!(nodes.add_row(tskit::NodeFlags::IS_SAMPLE, 10., -1, -1).is_ok());
289-
/// # assert_eq!(nodes.num_rows(), 1);
290-
/// let flags = nodes.flags_array_mut();
291-
/// # assert_eq!(flags.len(), 1);
292-
/// assert!(flags.iter().all(|f| f.is_sample()));
293-
///
294-
/// // while we are at it, let's use our node
295-
/// // table to populate a table collection.
296-
/// #
297-
/// let mut tables = tskit::TableCollection::new(10.0).unwrap();
298-
/// tables.set_nodes(&nodes);
299-
/// assert_eq!(tables.nodes().num_rows(), 1);
300-
/// assert_eq!(tables.nodes_mut().flags_array_mut().iter().filter(|f| f.is_sample()).count(), 1);
301-
/// ```
302-
///
303-
/// # Note
304-
///
305-
/// Internally, we rely on a conversion of u64 to usize.
306-
/// This conversion is fallible on some platforms.
307-
/// If the conversion fails, an empty slice is returned.
232+
#[deprecated(since = "0.12.0", note = "use flags_slice_mut instead")]
308233
pub fn flags_array_mut(&mut self) -> &mut [NodeFlags] {
309234
unsafe {
310235
std::slice::from_raw_parts_mut(
@@ -314,38 +239,7 @@ impl NodeTable {
314239
}
315240
}
316241

317-
/// Mutable access to node times.
318-
///
319-
/// # Examples
320-
///
321-
/// For a [`crate::TableCollection`], accessing the table creates a temporary
322-
/// that will be dropped, causing this code to not compile:
323-
///
324-
/// ```compile_fail
325-
/// # use tskit::prelude::*;
326-
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
327-
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
328-
/// let time = tables.nodes().time_array_mut();
329-
/// println!("{}", time.len()); // ERROR: the temporary node table is dropped by now
330-
/// ```
331-
///
332-
/// Treating the returned slice as an iterable succeeds:
333-
///
334-
/// ```
335-
/// # use tskit::prelude::*;
336-
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
337-
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
338-
/// for time in tables.nodes_mut().time_array_mut() {
339-
/// *time = 55.0.into(); // change each node's time value
340-
/// }
341-
/// assert!(tables.nodes_mut().time_array_mut().iter().all(|t| t == &55.0));
342-
/// ```
343-
///
344-
/// # Note
345-
///
346-
/// Internally, we rely on a conversion of u64 to usize.
347-
/// This conversion is fallible on some platforms.
348-
/// If the conversion fails, an empty slice is returned.
242+
#[deprecated(since = "0.12.0", note = "use time_slice_mut instead")]
349243
pub fn time_array_mut(&mut self) -> &mut [Time] {
350244
unsafe {
351245
std::slice::from_raw_parts_mut(
@@ -528,7 +422,38 @@ impl NodeTable {
528422
/// Get the time column as a slice
529423
=> time, time_slice_raw, f64);
530424
build_table_column_slice_mut_getter!(
531-
/// Get the time column as a mutable slice
425+
/// Get the time column as a mutable slice
426+
///
427+
/// # Examples
428+
///
429+
/// For a [`crate::TableCollection`], accessing the table creates a temporary
430+
/// that will be dropped, causing this code to not compile:
431+
///
432+
/// ```compile_fail
433+
/// # use tskit::prelude::*;
434+
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
435+
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
436+
/// let time = tables.nodes().time_slice_mut();
437+
/// println!("{}", time.len()); // ERROR: the temporary node table is dropped by now
438+
/// ```
439+
///
440+
/// Treating the returned slice as an iterable succeeds:
441+
///
442+
/// ```
443+
/// # use tskit::prelude::*;
444+
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
445+
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
446+
/// for time in tables.nodes_mut().time_slice_mut() {
447+
/// *time = 55.0.into(); // change each node's time value
448+
/// }
449+
/// assert!(tables.nodes_mut().time_slice_mut().iter().all(|t| t == &55.0));
450+
/// ```
451+
///
452+
/// # Panics
453+
///
454+
/// Internally, we rely on a conversion of u64 to usize.
455+
/// This conversion is fallible on some platforms.
456+
/// If the conversion fails, this function will panic.
532457
=> time, time_slice_mut, Time);
533458
build_table_column_slice_mut_getter!(
534459
/// Get the time column as a mutable slice
@@ -540,7 +465,82 @@ impl NodeTable {
540465
/// Get the flags column as a slice
541466
=> flags, flags_slice_raw, ll_bindings::tsk_flags_t);
542467
build_table_column_slice_mut_getter!(
543-
/// Get the flags column as a mutable slice
468+
/// Get the flags column as a mutable slice
469+
///
470+
/// # Examples
471+
///
472+
///
473+
/// ```
474+
/// # use tskit::prelude::*;
475+
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
476+
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
477+
/// let flags = tables.nodes_mut().flags_slice_mut();
478+
/// for flag in flags {
479+
/// // Can do something...
480+
/// # assert!(flag.is_sample());
481+
/// }
482+
/// ```
483+
///
484+
/// ```
485+
/// # use tskit::prelude::*;
486+
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
487+
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
488+
/// for flag in tables.nodes_mut().flags_slice_mut() {
489+
/// # assert!(flag.is_sample());
490+
/// }
491+
/// ```
492+
///
493+
/// The returned slice is *mutable*, allowing one to do things like
494+
/// clear the sample status of all nodes:
495+
///
496+
/// A copy of the flags can be obtained by collecting results into `Vec`:
497+
///
498+
/// ```
499+
/// # use tskit::prelude::*;
500+
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
501+
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
502+
/// for flag in tables.nodes_mut().flags_slice_mut() {
503+
/// flag.remove(tskit::NodeFlags::IS_SAMPLE);
504+
/// }
505+
/// assert!(!tables.nodes_mut().flags_slice_mut().iter().any(|f| f.is_sample()));
506+
/// assert!(tables.nodes().samples_as_vector().is_empty());
507+
/// ```
508+
///
509+
/// ```
510+
/// # use tskit::prelude::*;
511+
/// # let mut tables = tskit::TableCollection::new(10.).unwrap();
512+
/// # tables.add_node(tskit::NodeFlags::IS_SAMPLE, 10.0, -1, -1).unwrap();
513+
/// let flags = tables.nodes_mut().flags_slice_mut().to_vec();
514+
/// # assert!(flags.iter().all(|f| f.is_sample()));
515+
/// ```
516+
///
517+
/// ## Standalone tables
518+
///
519+
/// The ownership semantics differ when tables are not part of a
520+
/// table collection:
521+
///
522+
/// ```
523+
/// let mut nodes = tskit::OwnedNodeTable::default();
524+
/// assert!(nodes.add_row(tskit::NodeFlags::IS_SAMPLE, 10., -1, -1).is_ok());
525+
/// # assert_eq!(nodes.num_rows(), 1);
526+
/// let flags = nodes.flags_slice_mut();
527+
/// # assert_eq!(flags.len(), 1);
528+
/// assert!(flags.iter().all(|f| f.is_sample()));
529+
///
530+
/// // while we are at it, let's use our node
531+
/// // table to populate a table collection.
532+
/// #
533+
/// let mut tables = tskit::TableCollection::new(10.0).unwrap();
534+
/// tables.set_nodes(&nodes);
535+
/// assert_eq!(tables.nodes().num_rows(), 1);
536+
/// assert_eq!(tables.nodes_mut().flags_slice_mut().iter().filter(|f| f.is_sample()).count(), 1);
537+
/// ```
538+
///
539+
/// # Panics
540+
///
541+
/// Internally, we rely on a conversion of u64 to usize.
542+
/// This conversion is fallible on some platforms.
543+
/// If the conversion fails, this function will panic.
544544
=> flags, flags_slice_mut, NodeFlags);
545545
build_table_column_slice_mut_getter!(
546546
/// Get the flags column as a mutable slice

0 commit comments

Comments
 (0)