Struct raccoon::series::Series

pub struct Series { /* fields omitted */ }

A growable, named series. This tries to conform to the behaviour of python's pandas.Series.

Examples

use raccoon::{Series, DataType, DataEntry};

let mut series = Series::new("My Series".to_owned(), DataType::Double);
series.push(3.45f64);
series.push(67.8f64);

assert_eq!(series.len(), 2);
assert_eq!(series[0], DataEntry::Double(3.45));

series.push_vec(vec![2.0f64, 2.1, 2.2, 2.3]);

In general, this can be seen as a special type of vector, allowing aggregate operations. However, one major major difference, is the fact that a Series cannot be indexed mutably. Hence code such as the following will cause a compilation error:

let mut series = Series::from(vec![1, 2, 3]);
series[0] = 5;          // compile time error

The reason for prohibiting mutable indexing is to ensure data type integrity. Code such as the following would otherwise run without problems:

// creating a series containing boolean values
let mut series = Series::from(vec![true, false, true]);

// setting the second value to an integer
series[1] = DataEntry::Integer(32);     // should NOT be allowed!!

Methods

impl Series

pub fn new(name: String, data_type: DataType) -> Series

Constructs a new, empty Series with the specified name and data type.

Example

use raccoon::{Series, DataType};

let series = Series::new("My Series".to_owned(), DataType::Float);
assert!(series.is_empty());
assert_eq!("My Series", series.name());

pub fn with_capacity(     name: String,     data_type: DataType,     capacity: usize ) -> Series

Constructs a new, empty Series with the specified name, data type, and capacity.

The series will be able to hold exactly capacity elements without reallocating. It is important to note that although the returned series will have the capacity specified, the series will have zero length. See Rust's documentation of std::vec::Vec<T> for the difference between length and capacity.

Example

use raccoon::{Series, DataType, DataEntry};

let mut series = Series::with_capacity("series1".to_owned(), DataType::Integer, 10);

// the series contain no items even though it has capacity for more
assert!(series.is_empty());

// these are all done without reallocation
for i in 0i32..10i32 {
    series.push(i);
}

// ... but this may make the series reallocate
series.push(11);

pub fn push<T>(&mut self, data: T) -> RaccoonResult where     T: Into<DataEntry>,

Append a data entry to the series.

As this uses type inference to add the data entry, ensure the append occured. data must match the internal type used by the series.

Example

// using `i32` to create the series
let mut series = Series::from(vec![0, 1, 2, 3]);

// ... hence the type is `DataType::Integer`
assert_eq!(series.data_type(), &DataType::Integer);

// works
let result = series.push(4);
assert!(result.is_ok());
assert_eq!(series[4], DataEntry::Integer(4));

// fails
let result = series.push(5.0);      // f32
assert!(result.is_err());

pub fn push_vec<T>(&mut self, vector: Vec<T>) -> RaccoonResult where     T: Into<DataEntry>,

Extend the series by a data vector.

As this uses type inference to add the data entry, ensure the append occured. data must match the internal type used by the series.

Example

// using `i32` to create the series
let mut series = Series::from(vec![0, 1, 2, 3]);

// ... hence the type is `DataType::Integer`
assert_eq!(series.data_type(), &DataType::Integer);

// works
let result = series.push_vec(vec![4, 5, 6]);
assert!(result.is_ok());
assert_eq!(series[6], DataEntry::Integer(6));

// fails
let result = series.push_vec(vec![3.4, 5.6, 1.2]);      // f32
assert!(result.is_err());

pub fn push_entry(&mut self, data_entry: DataEntry) -> RaccoonResult

Append a DataEntry object to the series.

Example

// using `i32` to create the series
let mut series = Series::from(vec![0, 1, 2, 3]);

// ... hence the type is `DataType::Integer`
assert_eq!(series.data_type(), &DataType::Integer);

// works
let result = series.push_entry(DataEntry::Integer(4));
assert!(result.is_ok());
assert_eq!(series[4], DataEntry::Integer(4));

// fails
let result = series.push(DataEntry::Float(5.0));
assert!(result.is_err());

pub fn push_entry_vec(&mut self, vector: Vec<DataEntry>) -> RaccoonResult

Append a DataEntry vector to the series.

Example

// using `i32` to create the series
let mut series = Series::from(vec![0, 1, 2, 3]);

// ... hence the type is `DataType::Integer`
assert_eq!(series.data_type(), &DataType::Integer);

// works
let vector = vec![
    DataEntry::Integer(4),
    DataEntry::Integer(5),
    DataEntry::Integer(6),
];
let result = series.push_entry_vec(vector);
assert!(result.is_ok());
assert_eq!(series[6], DataEntry::Integer(6));

// fails
let vector = vec![
    DataEntry::Float(3.4),
    DataEntry::Float(5.6),
    DataEntry::Float(1.2),
];
let result = series.push_entry_vec(vector);
assert!(result.is_err());

pub fn pop_entry(&mut self) -> Option<DataEntry>

Pops an entry from the end of the series.

Example

let mut series = Series::new("series1".to_owned(), DataType::Boolean);
series.push(true);

assert_eq!(1, series.len());
let result = series.pop_entry();
assert_eq!(Some(DataEntry::Boolean(true)), result);

assert!(series.is_empty());
let result = series.pop_entry();
assert_eq!(None, result);

pub fn len(&self) -> usize

Returns the length of the series.

Example

let series = Series::from(vec![1, 2, 3]);
assert_eq!(3, series.len())

pub fn convert_to(&mut self, data_type: &DataType)

Converts the series into another data type.

Note that some data types cannot be converted into one another as the conversion makes no sense. This results in DataType::NA entries. The conversion from numerical types into boolean values is performed by checking equality with 0.

Conversions that result in DataType::NA

• DataType::Text into another type that cannot be parsed into another type using String::from(). For example the conversion shown in the third example of this docstring.
• DataType::Character into DataType::Boolean.
• Anything except DataType::Text into DataType::Character. This can be somewhat circumvented by converting to DataType::Text and then into DataType::Character.
• Any signed numerical type into an unsigned one.
• DataType::Long into DataType::Integer.
• DataType::ULong into DataType::UInteger.

Examples

A working conversion:

let mut series = Series::from(vec![true, true, false, true]);
series.convert_to(&DataType::Integer);
assert_eq!(series, vec![1, 1, 0, 1]);

A working yet lossy conversion:

// build double precision floating point series
let mut series = Series::from(vec![123.456f64, 456.789f64]);
assert_eq!(series.data_type(), &DataType::Double);

// convert to single precision floating point
series.convert_to(&DataType::Float);
assert_eq!(series.data_type(), &DataType::Float);
assert_eq!(series, vec![123.456f32, 456.789f32]);

A conversion that makes no sense:

let mut series = Series::from(vec!["some", "random", "words"]);
series.convert_to(&DataType::Character);
assert_eq!(series, vec![DataEntry::NA, DataEntry::NA, DataEntry::NA]);

pub fn data_type(&self) -> &DataType

Getter for the series' data type.

Example

let series = Series::new("my series".to_owned(), DataType::ULong);
assert_eq!(series.data_type(), &DataType::ULong);

pub fn from_vector<T>(name: String, vector: Vec<T>) -> Series where     T: Into<DataEntry>,

Builds a Series from a vector of items and gives the series a name.

Example

let series = Series::from_vector("my series".to_owned(), vec![1, 2, 3]);
assert_eq!(series.name(), "my series");
assert_eq!(series, vec![1, 2, 3]);

pub fn name(&self) -> &str

Getter for the series' name.

Example

let series = Series::new("custom name".to_owned(), DataType::Character);
assert_eq!(series.name(), "custom name");

pub fn set_name(&mut self, name: String)

Setter for the series' name.

Example

let mut series = Series::from(vec!['a', 'b', 'c']);
assert_eq!(series.name(), "Series1");

// change name
series.set_name("custom name".to_owned());
assert_eq!(series.name(), "custom name");

pub fn is_empty(&self) -> bool

Checks if the series is empty.

Example

let mut series = Series::new("City".to_owned(), DataType::Text);
assert!(series.is_empty());

series.push("Zürich");
assert!(!series.is_empty());

Trait Implementations

impl Debug for Series

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

Formats the value using the given formatter.

impl Clone for Series

fn clone(&self) -> Series

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> From<Vec<T>> for Series where     T: Into<DataEntry>,

fn from(vector: Vec<T>) -> Self

Performs the conversion.

impl Index<usize> for Series

type Output = DataEntry

The returned type after indexing.

fn index(&self, idx: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl PartialEq for Series

fn eq(&self, other: &Series) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialEq<Vec<T>> for Series where     DataEntry: From<T>,     T: Clone,

fn eq(&self, other: &Vec<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.