Struct tskit::OwningIndividualTable
source · pub struct OwningIndividualTable { /* private fields */ }
Expand description
A standalone individual table that owns its data.
Examples
use tskit::OwningIndividualTable;
let mut individuals = OwningIndividualTable::default();
let rowid = individuals.add_row(0, None, None).unwrap();
assert_eq!(rowid, 0);
assert_eq!(individuals.num_rows(), 1);
An example with metadata.
This requires the cargo feature "derive"
for tskit
.
use tskit::OwningIndividualTable;
#[derive(serde::Serialize,
serde::Deserialize,
tskit::metadata::IndividualMetadata)]
#[serializer("serde_json")]
struct IndividualMetadata {
value: i32,
}
let metadata = IndividualMetadata{value: 42};
let mut individuals = OwningIndividualTable::default();
let rowid = individuals.add_row_with_metadata(0, None, None, &metadata).unwrap();
assert_eq!(rowid, 0);
match individuals.metadata::<IndividualMetadata>(rowid) {
// rowid is in range, decoding succeeded
Some(Ok(decoded)) => assert_eq!(decoded.value, 42),
// rowid is in range, decoding failed
Some(Err(e)) => panic!("error decoding metadata: {:?}", e),
None => panic!("row id out of range")
}
Implementations§
source§impl OwningIndividualTable
impl OwningIndividualTable
sourcepub fn clear(&mut self) -> TskReturnValue
pub fn clear(&mut self) -> TskReturnValue
Clear the table.
source§impl OwningIndividualTable
impl OwningIndividualTable
pub fn as_ptr(&self) -> *const tsk_individual_table_t
pub fn as_mut_ptr(&mut self) -> *mut tsk_individual_table_t
source§impl OwningIndividualTable
impl OwningIndividualTable
pub fn add_row<F, L, P>( &mut self, flags: F, location: L, parents: P ) -> Result<IndividualId, TskitError>where F: Into<IndividualFlags>, L: IndividualLocation, P: IndividualParents,
pub fn add_row_with_metadata<F, L, P, M>( &mut self, flags: F, location: L, parents: P, metadata: &M ) -> Result<IndividualId, TskitError>where F: Into<IndividualFlags>, L: IndividualLocation, P: IndividualParents, M: IndividualMetadata,
Methods from Deref<Target = IndividualTable>§
sourcepub fn flags<I: Into<IndividualId> + Copy>(
&self,
row: I
) -> Option<IndividualFlags>
pub fn flags<I: Into<IndividualId> + Copy>( &self, row: I ) -> Option<IndividualFlags>
sourcepub fn parents<I: Into<IndividualId> + Copy>(
&self,
row: I
) -> Option<&[IndividualId]>
pub fn parents<I: Into<IndividualId> + Copy>( &self, row: I ) -> Option<&[IndividualId]>
sourcepub fn metadata<T: IndividualMetadata>(
&self,
row: IndividualId
) -> Option<Result<T, TskitError>>
pub fn metadata<T: IndividualMetadata>( &self, row: IndividualId ) -> Option<Result<T, TskitError>>
Return the metadata for a given row.
Returns
Some(Ok(T))
ifrow
is valid and decoding succeeded.Some(Err(_))
ifrow
is not valid and decoding failed.None
ifrow
is not valid.
Errors
TskitError::MetadataError
if decoding fails.
Examples
For all examples, this is our metadata type.
We will add all instances with a value of x = 1
.
#[derive(serde::Serialize, serde::Deserialize, tskit::metadata::IndividualMetadata)]
#[serializer("serde_json")]
struct IndividualMetadata {
x: i32,
}
Without matches
// We know the metadata are here, so we unwrap the Option and the Result:
let decoded = tables.individuals().metadata::<IndividualMetadata>(0.into()).unwrap().unwrap();
assert_eq!(decoded.x, 1);
Checking for errors and absence of metadata
The Option<Result<_>>
return value allows all
three return possibilities to be easily covered:
match tables.individuals().metadata::<IndividualMetadata>(0.into())
{
Some(Ok(metadata)) => assert_eq!(metadata.x, 1),
Some(Err(_)) => panic!("got an error??"),
None => panic!("Got None??"),
};
Attempting to use the wrong type.
Let’s define a mutation metadata type with the exact same fields as our individual metadata defined above:
#[derive(serde::Serialize, serde::Deserialize, tskit::metadata::MutationMetadata)]
#[serializer("serde_json")]
struct MutationMetadata {
x: i32,
}
This type has the wrong trait bound and will cause compilation to fail:
match tables.individuals().metadata::<MutationMetadata>(0.into())
{
Some(Ok(metadata)) => assert_eq!(metadata.x, 1),
Some(Err(_)) => panic!("got an error??"),
None => panic!("Got None??"),
};
Limitations: different type, same trait bound
Finally, let us consider a different struct that has identical
fields to IndividualMetadata
defined above and also implements
the correct trait:
#[derive(serde::Serialize, serde::Deserialize, tskit::metadata::IndividualMetadata)]
#[serializer("serde_json")]
struct IndividualMetadataToo {
x: i32,
}
Let’s walk through a detailed example:
// create a mutable table collection
let mut tables = tskit::TableCollection::new(100.).unwrap();
// Create some metadata based on our FIRST type
let metadata = IndividualMetadata { x: 1 };
// Add a row with our metadata
assert!(tables.add_individual_with_metadata(0, None, None, &metadata).is_ok());
// Trying to fetch using our SECOND type as the generic type works!
match tables.individuals().metadata::<IndividualMetadataToo>(0.into())
{
Some(Ok(metadata)) => assert_eq!(metadata.x, 1),
Some(Err(_)) => panic!("got an error??"),
None => panic!("Got None??"),
};
What is going on here?
Both types satisfy the same trait bound (metadata::IndividualMetadata
)
and their data fields look identical to serde_json
.
Thus, one is exchangeable for the other because they have the exact same
behavior.
However, it is also true that this is (often/usually/always) not exactly what we want.
We are experimenting with encapsulation APIs involving traits with
associated
types to enforce at compile time that exactly one type (struct/enum
, etc.) is a valid
metadata type for a table.
sourcepub fn iter(&self) -> impl Iterator<Item = IndividualTableRow> + '_
pub fn iter(&self) -> impl Iterator<Item = IndividualTableRow> + '_
Return an iterator over rows of the table.
The value of the iterator is IndividualTableRow
.
pub fn lending_iter(&self) -> IndividualTableRowView<'_>
sourcepub fn row<I: Into<IndividualId> + Copy>(
&self,
r: I
) -> Option<IndividualTableRow>
pub fn row<I: Into<IndividualId> + Copy>( &self, r: I ) -> Option<IndividualTableRow>
sourcepub fn row_view<I: Into<IndividualId> + Copy>(
&self,
r: I
) -> Option<IndividualTableRowView<'_>>
pub fn row_view<I: Into<IndividualId> + Copy>( &self, r: I ) -> Option<IndividualTableRowView<'_>>
Return a view of r
of the table.
Parameters
r
: the row id.
Returns
Some(row view)
ifr
is validNone
otherwise
sourcepub fn flags_slice(&self) -> &[IndividualFlags]
pub fn flags_slice(&self) -> &[IndividualFlags]
Get the flags column as a slice
sourcepub fn flags_slice_raw(&self) -> &[tsk_flags_t]
pub fn flags_slice_raw(&self) -> &[tsk_flags_t]
Get the flags column as a slice