Struct rubbl_casatables::Table

pub struct Table { /* private fields */ }

A CASA data table.

Implementations

impl Table

A Rust wrapper for a casacore table.

For details on the casacore table concepts as expressed in the underlying C++ implementation, see the documentation.

pub fn new<P: AsRef<Path>>(
    path: P,
    table_desc: TableDesc,
    n_rows: usize,
    mode: TableCreateMode
) -> Result<Self, TableError>

Create a new casacore table.

To open an existing table, use Table::open.

Read more about the casacore tables C++ interface here.

Examples

Creating a table:

use std::path::PathBuf;
use tempfile::tempdir;
use rubbl_casatables::{
    ColumnDescription, GlueDataType, Table,
    TableCreateMode, TableDesc, TableDescCreateMode,
};

// tempdir is only necessary to avoid writing to disk each time this example is run
let tmp_dir = tempdir().unwrap();
let table_path = tmp_dir.path().join("test.ms");

// First create a table description for our base table.
// Use TDM_SCRATCH to avoid writing a `.tabdsc` file to disk.
let mut table_desc = TableDesc::new("", TableDescCreateMode::TDM_SCRATCH).unwrap();

// Define the columns in your table description:
table_desc.add_array_column(
    GlueDataType::TpDouble,                           // the data type
    "UVW",                                            // the column name
    Some("Vector with uvw coordinates (in meters)"),  // an optional comment about the column
    Some(&[3]),                                       // a required vector shape for the volumn
    true,                                             // "direct": whether data are stored in the table
    false,                                            // Whether some scalar values are treated as undefined
).unwrap();

// Create your new table with 0 rows.
Table::new(&table_path, table_desc, 0, TableCreateMode::New).unwrap();

pub fn open<P: AsRef<Path>>(
    path: P,
    mode: TableOpenMode
) -> Result<Self, TableError>

Open an existing casacore table.

To create a table, use Table::new. Do not use TableOpenMode::Create with this function — it will not do what you want.

Read more about the casacore tables C++ interface here.

Examples

Creating a table, writing a cell, opening it and reading the cell.

use std::path::PathBuf;
use tempfile::tempdir;
use rubbl_casatables::{ColumnDescription, GlueDataType, Table, TableCreateMode, TableDesc, TableDescCreateMode, TableOpenMode};

// tempdir is only necessary to avoid writing to disk each time this example is run
let tmp_dir = tempdir().unwrap();
let table_path = tmp_dir.path().join("test.ms");

// First create a table description for our base table.
// Use TDM_SCRATCH to avoid writing the .tabdsc to disk.
let mut table_desc = TableDesc::new("", TableDescCreateMode::TDM_SCRATCH).unwrap();

// Define the columns in your table description:
table_desc.add_array_column(
    GlueDataType::TpDouble,                           // the data type
    "UVW",                                            // the column name
    Some("Vector with uvw coordinates (in meters)"),  // an optional comment about the column
    Some(&[3]),                                       // a required vector shape for the volumn
    true,                                             // "direct": whether data are stored in the table
    false,                                            // Whether some scalar values are treated as undefined
).unwrap();

// Create the new table with 1 row.
let mut table = Table::new(&table_path, table_desc, 1, TableCreateMode::New).unwrap();

// Write to the first row in the uvw column
let cell_value: Vec<f64> = vec![1.0, 2.0, 3.0];
table.put_cell("UVW", 0, &cell_value).unwrap();

// This writes the table to disk and closes the file pointer:
drop(table);

// Now open the table:
let mut table = Table::open(&table_path, TableOpenMode::ReadWrite).unwrap();

// ... and extract the cell value we wrote earlier:
let extracted_cell_value: Vec<f64> = table.get_cell_as_vec("UVW", 0).unwrap();
assert_eq!(cell_value, extracted_cell_value);

Errors

Can raise CasacoreError if there was an issue invoking casacore.

pub fn n_rows(&self) -> u64

Get the number of rows in the table.

pub fn n_columns(&self) -> usize

Get the number of columns in the table.

pub fn file_name(&self) -> Result<String, CasacoreError>

Get the filesystem path associated with the table.

This function should only fail of the underlying C++ throws an exception, which should basically never happen for this operation.

pub fn column_names(&mut self) -> Result<Vec<String>, CasacoreError>

Get a vector containing all of the column names in the table.

Errors

Can raise CasacoreError if there was an issue invoking casacore

pub fn remove_column(&mut self, col_name: &str) -> Result<(), CasacoreError>

Remove a column from the table.

Errors

Can raise CasacoreError if there was an issue invoking casacore. To check: this probably returns an error if the named column was not present?

pub fn add_scalar_column(
    &mut self,
    data_type: GlueDataType,
    col_name: &str,
    comment: Option<&str>,
    direct: bool,
    undefined: bool
) -> Result<(), CasacoreError>

Add a scalar column to the table.

col_name - column name, must be unique

comment - optional string field describing how to use the column.

direct - Whether the underyling data are stored directly in the table. This should almost always be true.

Errors

Can raise CasacoreError if there was an issue invoking casacore

pub fn add_array_column(
    &mut self,
    data_type: GlueDataType,
    col_name: &str,
    comment: Option<&str>,
    dims: Option<&[u64]>,
    direct: bool,
    undefined: bool
) -> Result<(), TableError>

Add an array column to the Table

If dimensions (dims) are provided, then the column has fixed dimensions, other wise the column is not fixed.

pub fn table_keyword_names(&mut self) -> Result<Vec<String>, CasacoreError>

Return all of the names of keywords whose values are type TpTable.

pub fn column_keyword_names(
    &mut self,
    col_name: &str
) -> Result<Vec<String>, CasacoreError>

Return all of the names of keywords for a given column

pub fn put_table_keyword(
    &mut self,
    kw_name: &str,
    table: Table
) -> Result<(), CasacoreError>

Define a keyword of type TpTable in this table

pub fn put_keyword<T: CasaDataType>(
    &mut self,
    kw_name: &str,
    value: &T
) -> Result<(), CasacoreError>

Add a “keyword” to be associated with the table.

A keyword is essentially a name-value pair, where the associated value need not be a simple data type: it can be a record or even a sub-table.

See also Self::put_column_keyword.

pub fn put_column_keyword<T: CasaDataType>(
    &mut self,
    col_name: &str,
    kw_name: &str,
    value: &T
) -> Result<(), CasacoreError>

Add a “keyword” to be associated with a particular column of the table.

A keyword is essentially a name-value pair, where the associated value need not be a simple data type: it can be a record or even a sub-table.

See also Self::put_keyword for table-level keywords.

pub fn get_keyword_record(&mut self) -> Result<TableRecord, CasacoreError>

Return a TableRecord containing all keyword / value pairs for this table.

pub fn get_column_keyword_record(
    &mut self,
    col_name: &str
) -> Result<TableRecord, CasacoreError>

Return a TableRecord containing all keyword / value pairs for the named column.

pub fn get_col_desc(
    &mut self,
    col_name: &str
) -> Result<ColumnDescription, CasacoreError>

Get the description of the named column.

The returned ColumnDescription handle provides access to column’s data type, required vector shape, keywords, and other such metadata.

pub fn get_col_as_vec<T: CasaScalarData>(
    &mut self,
    col_name: &str
) -> Result<Vec<T>, TableError>

Get all of the data in a column as one vector.

The underlying data type of the column must be scalar. Use this function wisely since some CASA tables may contain millions of rows.

pub fn get_cell<T: CasaDataType>(
    &mut self,
    col_name: &str,
    row: u64
) -> Result<T, TableError>

Get the value of one cell of the table.

pub fn get_cell_as_vec<T: CasaScalarData>(
    &mut self,
    col_name: &str,
    row: u64
) -> Result<Vec<T>, TableError>

Get the contents of one cell of the table as a simple Rust vector.

This function discards shape information and won’t accept scalars.

pub fn put_cell<T: CasaDataType>(
    &mut self,
    col_name: &str,
    row: u64,
    value: &T
) -> Result<(), CasacoreError>

Put a value for one cell of the table.

pub fn add_rows(&mut self, n_rows: usize) -> Result<(), CasacoreError>

Add additional, empty rows to the table.

pub fn get_row_reader(&mut self) -> Result<TableRow, CasacoreError>

Get an object for read-only access to individual rows of the table.

The row reader can be used to iterate through the rows of the table efficiently.

See also Self::get_row_writer.

pub fn get_row_writer(&mut self) -> Result<TableRow, CasacoreError>

Get an object for read-write access to individual rows of the table.

The row writer can be used to iterate through the rows of the table efficiently.

See also Self::get_row_reader.

pub fn read_row(
    &mut self,
    row: &mut TableRow,
    row_number: u64
) -> Result<(), TableError>

Populate a TableRow accessor object with data from the specified row.

pub fn for_each_row<F>(&mut self, func: F) -> Result<(), TableError>where
    F: FnMut(&mut TableRow) -> Result<(), TableError>,

Perform func on each row of the table.

pub fn for_each_row_in_range<F>(
    &mut self,
    row_range: Range<u64>,
    func: F
) -> Result<(), TableError>where
    F: FnMut(&mut TableRow) -> Result<(), TableError>,

Perform func on each row in the range row_range.

pub fn for_each_specific_row<F>(
    &mut self,
    rows: &[u64],
    func: F
) -> Result<(), TableError>where
    F: FnMut(&mut TableRow) -> Result<(), TableError>,

Perform func on each row indicated by rows.

pub fn copy_rows_to(&mut self, dest: &mut Table) -> Result<(), CasacoreError>

Copy all rows from this table to another table.

pub fn deep_copy_no_rows(&mut self, dest_path: &str) -> Result<(), CasacoreError>

Copy the “description” of this table to a new filesystem path, without copying any of the actual data contents.

Trait Implementations

impl Debug for Table

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Table

fn drop(&mut self)

Executes the destructor for this type.