Struct Screener 

pub struct Screener {
    pub subtype: String,
    /* private fields */
}

Request builder for one scanner POST.

Holds columns, filters, range, sort, markets/symbols, and a reused [reqwest::Client]. Self::build_payload builds the JSON body; Self::get POSTs to scanner.tradingview.com/{subtype}/scan and returns ScreenerRows. Prefer typed wrappers (StockScreener, CryptoScreener, …) which set subtype and defaults; use this type when you need the raw builder.

Override the timeout with Self::set_timeout before Self::get.

Payload example

use tvscreener::core::Screener;
use tvscreener::field::{index_symbol, FieldDef, Market};
use tvscreener::filter::{FieldCondition, FilterOperator};
use serde_json::json;

let mut screener = Screener::new("global");
screener
.select([FieldDef::new("Name", "name")])
.set_markets([Market::america().value])
.set_index([index_symbol::SP500])
.where_condition(FieldCondition::new(
"close",
FilterOperator::Above,
json!(50),
)).unwrap()
.set_range(0, 10);
let payload = screener.build_payload().unwrap();
assert_eq!(payload["markets"], json!(["america"]));
assert_eq!(payload["symbols"]["symbolset"], json!(["SYML:SP;SPX"]));

Fields

subtype: String

Path segment in https://scanner.tradingview.com/{subtype}/scan.

Implementations

impl Screener

pub fn new(subtype: impl Into<String>) -> Self

Creates a screener targeting subtype (e.g. "crypto", "global" for stocks).

pub fn set_timeout(&mut self, timeout: Duration) -> &mut Self

Overrides the HTTP request timeout (default: DEFAULT_TIMEOUT_SECS).

Rebuilds the shared [reqwest::Client] so the new timeout applies to later Self::get / stream calls.

pub const fn timeout(&self) -> Duration

Returns the configured HTTP timeout.

pub fn set_url(&mut self, url: impl Into<String>) -> &mut Self

Overrides the POST URL (defaults to crate::util::get_url for Self::subtype).

pub fn set_all_fields_fn(&mut self, f: fn() -> Vec<FieldDef>) -> &mut Self

Registers the callback used by Self::select_all

pub fn select( &mut self, fields: impl IntoIterator<Item = FieldDef>, ) -> &mut Self

Restricts requested columns, replacing any prior selection

pub fn select_all(&mut self) -> Result<&mut Self>

Requests the field set registered by Self::set_all_fields_fn

Errors

Returns TvscreenerError::InvalidRequest when set_all_fields_fn was not called.

pub fn filter_left_allowed(&self, left: &str) -> bool

Returns whether left is allowed when Self::validate_filter_fields is enabled.

Always allows ExtraFilter keys and stock structural keys type / subtype. Otherwise requires a match against Self::set_all_fields_fn defaults when set, else the currently selected columns’ technical names.

pub const fn set_validate_filter_fields(&mut self, enable: bool) -> &mut Self

Enables or disables filter-field validation (default: off).

pub const fn validate_filter_fields(&self) -> bool

Returns whether filter left keys are validated against the allowed field set.

pub fn add_filter( &mut self, left: impl Into<String>, operation: FilterOperator, values: impl IntoIterator<Item = Value>, ) -> Result<&mut Self>

Appends or merges a filter clause.

Errors

Returns TvscreenerError::InvalidFieldName when validation is enabled and left is not in the allowed set.

pub fn add_extra_filter( &mut self, extra: ExtraFilter, operation: FilterOperator, values: impl IntoIterator<Item = Value>, ) -> Result<&mut Self>

Appends or merges a filter on an ExtraFilter left key.

Errors

Propagates Self::add_filter errors (extra keys are always allowed).

pub fn where_condition( &mut self, condition: FieldCondition, ) -> Result<&mut Self>

Appends or merges a filter from a FieldCondition.

Errors

Propagates Self::add_filter errors.

pub fn search(&mut self, value: impl Into<String>) -> Result<&mut Self>

Adds a name/description search filter.

Errors

Propagates Self::add_extra_filter errors.

pub fn remove_filter(&mut self, left: &str) -> &mut Self

Removes the first filter whose left matches

pub const fn set_range(&mut self, from_range: u32, to_range: u32) -> &mut Self

Sets the [from, to) result window

pub fn sort_by( &mut self, field_name: impl Into<String>, ascending: bool, ) -> &mut Self

Sets sort column and direction by technical field name

pub fn sort_by_field(&mut self, field: &FieldDef, ascending: bool) -> &mut Self

Sets sort column from a FieldDef (uses FieldDef::field_name).

pub const fn set_debug(&mut self, enable: bool) -> &mut Self

Enables debug logging of scan URL and JSON payload (via tracing at DEBUG).

Also enabled for the process when TVSCREENER_DEBUG=1 (payload dump) after crate::logging::init_logging, or when RUST_LOG includes tvscreener=debug.

pub const fn set_print_request(&mut self, enable: bool) -> &mut Self

Alias for Self::set_debug.

pub fn add_option(&mut self, key: impl Into<String>, value: Value) -> &mut Self

Adds one scan options entry

pub fn add_misc(&mut self, key: impl Into<String>, value: Value) -> &mut Self

Adds one top-level payload key outside filter/columns

pub fn set_index( &mut self, symbolsets: impl IntoIterator<Item = impl Into<String>>, ) -> &mut Self

Restricts results to index symbol sets.

Catalog values like "SP;SPX" are sent as "SYML:SP;SPX". Values already prefixed with SYML: are left unchanged.

pub fn set_symbols(&mut self, symbols: Value) -> &mut Self

Sets the symbols block on the payload

pub fn set_markets( &mut self, markets: impl IntoIterator<Item = impl Into<String>>, ) -> &mut Self

Sets market filters included as top-level "markets" (stock screener).

pub fn filters(&self) -> &[Filter]

Returns configured filters (read-only view for tests and debugging).

pub const fn is_select_all(&self) -> bool

Returns whether select_all was enabled.

pub const fn range(&self) -> (u32, u32)

Returns the configured result range (from, to).

pub fn selected_fields(&self) -> &[FieldDef]

Returns the selected field definitions.

pub fn build_payload(&self) -> Result<Value>

Builds the JSON POST body

Errors

Returns TvscreenerError::InvalidRequest when no fields were selected.

pub fn parse_rows( body: &Value, columns: &[(String, String)], ) -> Result<Vec<ScreenerRow>>

Parses a scanner JSON body into ScreenerRow values keyed by column labels.

Errors

Returns TvscreenerError::Json when data, row symbols, or row value arrays are missing or malformed.

pub async fn get(&self) -> Result<Vec<ScreenerRow>>

Runs the scan and returns decoded rows

Errors

Propagates TvscreenerError::InvalidRequest, HTTP/network failures, non-success status codes, JSON parse errors, and row decode failures.

pub async fn stream_with_callback<F>( &self, interval_secs: f64, max_iterations: Option<usize>, on_update: F, )

where F: FnMut(&[ScreenerRow]),

Polls Self::get on an interval, invoking on_update for each successful batch.

pub async fn stream( &self, interval_secs: f64, max_iterations: Option<usize>, ) -> Vec<Vec<ScreenerRow>>

Polls Self::get and returns each successful batch (errors are logged and skipped).

Trait Implementations

impl Clone for Screener

fn clone(&self) -> Screener

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Screener

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

Formats the value using the given formatter.