From c8c7157de5998c27122a1fd81d5e322d3b34e171 Mon Sep 17 00:00:00 2001
From: Jason Nguyen <dat.nguyen@bitbytelab.io>
Date: Fri, 15 Sep 2023 16:05:12 +0700
Subject: [PATCH] added some docs

---
 examples/csv_export.rs | 63 ++++++++++++++++++++++++++++++++++++++++++
 src/chart/utils.rs     | 58 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 examples/csv_export.rs

diff --git a/examples/csv_export.rs b/examples/csv_export.rs
new file mode 100644
index 0000000..c3646b9
--- /dev/null
+++ b/examples/csv_export.rs
@@ -0,0 +1,63 @@
+use std::env;
+
+use tracing::info;
+use tradingview_rs::{
+    chart::{
+        session::{ChartCallbackFn, WebSocket},
+        ChartOptions, ChartSeries,
+    },
+    models::Interval,
+    socket::DataServer,
+};
+
+#[tokio::main]
+async fn main() {
+    tracing_subscriber::fmt::init();
+    let auth_token = env::var("TV_AUTH_TOKEN").unwrap();
+
+    let handlers = ChartCallbackFn {
+        on_chart_data: Box::new(|data| Box::pin(on_chart_data(data))),
+        on_symbol_resolved: Box::new(|data| Box::pin(on_symbol_resolved(data))),
+        on_series_completed: Box::new(|data| Box::pin(on_series_completed(data))),
+    };
+
+    let mut socket = WebSocket::build()
+        .server(DataServer::ProData)
+        .auth_token(auth_token)
+        .connect(handlers)
+        .await
+        .unwrap();
+
+    socket
+        .set_market(
+            "BINANCE:BTCUSDT",
+            ChartOptions {
+                resolution: Interval::OneMinute,
+                bar_count: 50_000,
+                ..Default::default()
+            },
+        )
+        .await
+        .unwrap();
+    socket.subscribe().await;
+}
+
+async fn on_chart_data(data: ChartSeries) -> Result<(), tradingview_rs::error::Error> {
+    let end = data.data.first().unwrap().timestamp;
+    info!("on_chart_data: {:?} - {:?}", data.data.len(), end);
+    Ok(())
+}
+
+async fn on_symbol_resolved(
+    data: tradingview_rs::chart::SymbolInfo,
+) -> Result<(), tradingview_rs::error::Error> {
+    info!("on_symbol_resolved: {:?}", data);
+    Ok(())
+}
+
+async fn on_series_completed(
+    data: tradingview_rs::chart::SeriesCompletedMessage,
+) -> Result<(), tradingview_rs::error::Error> {
+    info!("on_series_completed: {:?}", data);
+    Ok(())
+}
diff --git a/src/chart/utils.rs b/src/chart/utils.rs
index 036dc3b..0941871 100644
--- a/src/chart/utils.rs
+++ b/src/chart/utils.rs
@@ -6,6 +6,15 @@ use rayon::prelude::*;
 use serde_json::Value;
 use std::sync::Mutex;
 
+/// Extracts OHLCV data from a `ChartResponseData` object and returns a vector of `OHLCV` structs.
+///
+/// # Arguments
+///
+/// * `data` - A reference to a `ChartResponseData` object containing the series data.
+///
+/// # Returns
+///
+/// A vector of `OHLCV` structs containing the extracted data.
 pub fn extract_ohlcv_data(data: &ChartResponseData) -> Vec<OHLCV> {
     data.series
         .iter()
@@ -20,6 +29,15 @@ pub fn extract_ohlcv_data(data: &ChartResponseData) -> Vec<OHLCV> {
         .collect()
 }
 
+/// Extracts the data from a `StudyResponseData` object and returns it as a vector of vectors.
+///
+/// # Arguments
+///
+/// * `data` - A reference to a `StudyResponseData` object.
+///
+/// # Returns
+///
+/// A vector of vectors containing the data from the `StudyResponseData` object.
 pub fn extract_studies_data(data: &StudyResponseData) -> Vec<Vec<f64>> {
     data.studies
         .iter()
@@ -27,6 +45,15 @@ pub fn extract_studies_data(data: &StudyResponseData) -> Vec<Vec<f64>> {
         .collect()
 }
 
+/// Extracts OHLCV data from a `ChartResponseData` struct in parallel.
+///
+/// # Arguments
+///
+/// * `data` - A reference to a `ChartResponseData` struct.
+///
+/// # Returns
+///
+/// A vector of `OHLCV` structs.
 pub fn par_extract_ohlcv_data(data: &ChartResponseData) -> Vec<OHLCV> {
     data.series
         .par_iter()
@@ -41,6 +68,12 @@ pub fn par_extract_ohlcv_data(data: &ChartResponseData) -> Vec<OHLCV> {
         .collect()
 }
 
+/// Sorts an array of OHLCV tuples by their timestamp in ascending order.
+///
+/// # Arguments
+///
+/// * `tuples` - A mutable reference to an array of OHLCV tuples to be sorted.
+///
 pub fn sort_ohlcv_tuples(tuples: &mut [OHLCV]) {
     tuples.sort_by(|a, b| {
         a.timestamp
@@ -49,6 +82,15 @@ pub fn sort_ohlcv_tuples(tuples: &mut [OHLCV]) {
     });
 }
 
+/// Update an OHLCV data point in a vector of OHLCV data.
+///
+/// If a data point with the same timestamp as `new_data` exists in `data`, it will be updated with `new_data`.
+/// Otherwise, `new_data` will be added to `data` and the vector will be sorted by timestamp.
+///
+/// # Arguments
+///
+/// * `data` - A mutable reference to a vector of OHLCV data.
+/// * `new_data` - The new OHLCV data point to update or add to `data`.
 pub fn update_ohlcv_data_point(data: &mut Vec<OHLCV>, new_data: OHLCV) {
     if let Some(index) = data
         .iter()
@@ -65,6 +107,20 @@ pub fn update_ohlcv_data_point(data: &mut Vec<OHLCV>, new_data: OHLCV) {
     }
 }
 
+/// Updates the OHLCV data by merging the new data into the old data.
+///
+/// # Arguments
+///
+/// * `old_data` - A mutable reference to the old OHLCV data.
+/// * `new_data` - A reference to the new OHLCV data to be merged.
+///
+/// # Example
+///
+/// ```
+/// use tradingview_rs::tools::update_ohlcv_data;
+/// use tradingview_rs::models::OHLCV;
+///
+/// ```
 pub fn update_ohlcv_data(old_data: &mut Vec<OHLCV>, new_data: &Vec<OHLCV>) {
     let mutex = Mutex::new(old_data);
     new_data.par_iter().for_each(|op| {
@@ -73,6 +129,8 @@ pub fn update_ohlcv_data(old_data: &mut Vec<OHLCV>, new_data: &Vec<OHLCV>) {
     });
 }
 
+/// Returns the string value at the given index in the provided slice of `Value`s.
+/// If the value at the given index is not a string, an empty string is returned.
 pub fn get_string_value(values: &[Value], index: usize) -> String {
     match values.get(index) {
         Some(value) => match value.as_str() {