pub struct Obj(/* private fields */);
Expand description
A smart pointer that points to a referece-counted, heap-allocated Tcl value.
Implementations§
source§impl Obj
impl Obj
sourcepub unsafe fn from_raw(tcl_obj: *mut Tcl_Obj) -> Obj
pub unsafe fn from_raw(tcl_obj: *mut Tcl_Obj) -> Obj
Constructs an Obj
from a raw pointer.
§Safety
The raw pointer should be provided by Tcl’s callback, or previously obtained by Obj::as_ptr()
.
sourcepub fn into_raw(self) -> *mut Tcl_Obj
pub fn into_raw(self) -> *mut Tcl_Obj
Consumes the obj, returning the raw pointer.
To avoid a memory leak the pointer must be converted back to an Obj
using Obj::from_raw
.
sourcepub fn get_string(&self) -> String
pub fn get_string(&self) -> String
Return an obj’s string representation. If the value’s MUTF string representation is invalid, the string representation is regenerated from the value’s internal representation.
sourcepub fn invalidate_string_rep(&self)
pub fn invalidate_string_rep(&self)
Marks an obj’s string representation invalid and to free any storage associated with the old string representation.
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Test if tcl::Obj
has no value.
A newly created Obj
is guaranteed to be dummy.
An empty string is considered to be dummy.
§Example
assert!( tcl::Obj::new().is_empty() );
assert!( tcl::Obj::from("").is_empty() );
assert!( !tcl::Obj::from("hello").is_empty() );
Checks if the reference count of this obj is greater than 1.
sourcepub fn clone_value(&self) -> Option<Obj>
pub fn clone_value(&self) -> Option<Obj>
Clones the underlying value of this obj.
source§impl Obj
impl Obj
sourcepub fn new_dict() -> Obj
pub fn new_dict() -> Obj
Creates a new, empty dictionary value.
§Examples
use tcl::*;
let dict = Obj::new_dict();
assert_eq!( dict.to_string(), "" );
sourcepub fn dict_get(&self, key: impl Into<Obj>) -> Result<Option<Obj>, NotDict>
pub fn dict_get(&self, key: impl Into<Obj>) -> Result<Option<Obj>, NotDict>
Looks up the given key within the given dictionary and returns the value associated with that key,
or None
if the key has no mapping within the dictionary.
An error of NotDict
occurs if it cannot be converted to a dictionary.
§Examples
use std::collections::HashMap;
use tcl::*;
let mut map = HashMap::new();
map.insert( "C" , 1972 );
map.insert( "C++" , 1983 );
map.insert( "Rust", 2006 );
let map = Obj::from( map );
assert!( map.dict_get("Cpp").unwrap().is_none() );
assert_eq!( map.dict_get("Rust").unwrap().unwrap().as_i32(), 2006 );
sourcepub fn dict_put(
&self,
key: impl Into<Obj>,
value: impl Into<Obj>
) -> Result<(), Enum2<MutateSharedDict, NotDict>>
pub fn dict_put( &self, key: impl Into<Obj>, value: impl Into<Obj> ) -> Result<(), Enum2<MutateSharedDict, NotDict>>
Updates the given dictionary so that the given key maps to the given value;
any key may exist at most once in any particular dictionary.
The dictionary must not be shared, or an error of MutateSharedDict
will occur.
An error of NotDict
occurs if it cannot be converted to a dictionary.
§Examples
use std::collections::HashMap;
use tcl::*;
let dict = Obj::new_dict();
assert_eq!( dict.to_string(), "" );
dict.dict_put( "Rust", 2006 );
assert_eq!( dict.to_string(), "Rust 2006" );
sourcepub fn dict_remove(
&self,
key: impl Into<Obj>
) -> Result<(), Enum2<MutateSharedDict, NotDict>>
pub fn dict_remove( &self, key: impl Into<Obj> ) -> Result<(), Enum2<MutateSharedDict, NotDict>>
Updates the given dictionary so that the given key has no mapping to any value.
The dictionary must not be shared, or an error of MutateSharedDict
will occur.
It is not an error if the key did not previously exist.
An error of NotDict
occurs if it cannot be converted to a dictionary.
§Examples
use std::collections::HashMap;
use tcl::*;
let mut map = HashMap::new();
map.insert( "C++" , 1983 );
map.insert( "Rust", 2006 );
let map = Obj::from( map );
map.dict_remove("Cpp").unwrap();
map.dict_remove("C++").unwrap();
assert_eq!( map.to_string(), "Rust 2006" );
sourcepub fn dict_size(&self) -> Result<c_int, NotDict>
pub fn dict_size(&self) -> Result<c_int, NotDict>
Updates the given variable with the number of key/value pairs currently in the given dictionary.
An error of NotDict
occurs if it cannot be converted to a dictionary.
§Examples
use std::collections::HashMap;
use tcl::*;
let mut map = HashMap::new();
map.insert( "C++" , 1983 );
map.insert( "Rust", 2006 );
let map = Obj::from( map );
assert_eq!( map.dict_size().unwrap(), 2 );
let obj = vec![ "C++", "1983", "Rust", "2006" ];
assert_eq!( map.dict_size().unwrap(), 2 );
sourcepub fn dict_iter(self) -> Result<DictIter, NotDict>
pub fn dict_iter(self) -> Result<DictIter, NotDict>
Creates an iterator from a dictionary.
§Examples
use std::collections::HashMap;
use tcl::*;
let mut map = HashMap::new();
map.insert( "C" , 1972 );
map.insert( "C++" , 1983 );
map.insert( "Rust", 2006 );
let map = Obj::from( map );
let mut list = map
.dict_iter()
.unwrap()
.map( |(k,v)| (k.to_string(), v.as_i32() ))
.collect::<Vec<_>>();
list.sort();
assert_eq!( list, vec![ ("C".to_owned(),1972), ("C++".to_owned(),1983), ("Rust".to_owned(),2006) ]);
source§impl Obj
impl Obj
sourcepub fn new_list(objs: impl Iterator<Item = Obj>) -> Obj
pub fn new_list(objs: impl Iterator<Item = Obj>) -> Obj
Creates a new value as a Tcl list obj to hold objs
.
sourcepub fn new_list_with_capacity(cap: usize) -> Obj
pub fn new_list_with_capacity(cap: usize) -> Obj
Creates a new, empty Tcl list obj with the specified capacity.
sourcepub fn set_list(self, objs: impl Iterator<Item = Obj>) -> Self
pub fn set_list(self, objs: impl Iterator<Item = Obj>) -> Self
Sets the obj to hold a Tcl list composed of objs
.
sourcepub fn list_append(&self, to_append: impl Into<Obj>) -> Result<(), NotList>
pub fn list_append(&self, to_append: impl Into<Obj>) -> Result<(), NotList>
Append a list to_append
to this list.
§Examples
use tcl::*;
let list = Obj::from(( "The", "answer" ));
list.list_append(( "is", 42 ));
assert_eq!( list.to_string(), "The answer is 42" );
sourcepub fn list_append_element(&self, elem: impl Into<Obj>) -> Result<(), NotList>
pub fn list_append_element(&self, elem: impl Into<Obj>) -> Result<(), NotList>
Append an element elem
to this list.
§Examples
use tcl::*;
let list = Obj::from(( "The", "answer" ));
list.list_append_element(( "is", 42 ));
assert_eq!( list.to_string(), "The answer {is 42}" );
sourcepub fn get_elements(self) -> Result<impl Iterator<Item = Obj>, NotList>
pub fn get_elements(self) -> Result<impl Iterator<Item = Obj>, NotList>
Converts the list to an iterator that iterates over all its elements.
§Examples
use tcl::*;
let list = Obj::from(( "The", "answer", "is", 42 ));
let mut elems = list.get_elements().unwrap();
assert_eq!( elems.next().unwrap().to_string(), "The" );
assert_eq!( elems.next().unwrap().to_string(), "answer" );
assert_eq!( elems.next().unwrap().to_string(), "is" );
assert_eq!( elems.next().unwrap().as_i32(), 42 );
sourcepub fn list_length(&self) -> Result<c_int, NotList>
pub fn list_length(&self) -> Result<c_int, NotList>
Returns the amount of list elements.
§Examples
use tcl::*;
let list = Obj::from(( "The", "answer", "is", 42 ));
assert_eq!( list.list_length().unwrap(), 4 );
sourcepub fn list_index(&self, index: c_int) -> Result<Option<Obj>, NotList>
pub fn list_index(&self, index: c_int) -> Result<Option<Obj>, NotList>
Returns the nth obj in the list. Note that the index is 0-based.
§Examples
use tcl::*;
let list = Obj::from(( "The", "answer", "is", 42 ));
assert_eq!( list.list_index(1).unwrap().unwrap().to_string(), "answer" );
assert!( list.list_index(4).unwrap().is_none() );
sourcepub fn list_replace(
&self,
first: c_int,
count: c_int,
objs: impl Iterator<Item = Obj>
) -> Result<(), NotList>
pub fn list_replace( &self, first: c_int, count: c_int, objs: impl Iterator<Item = Obj> ) -> Result<(), NotList>
Replace from the first
to first
+count
objs in the list with objs
.
If the argument first
is zero or negative, it refers to the first element;
if it is greater than or equal to the number of elements in the list, then no elements are deleted;
the new elements are appended to the list.
If count is zero or negative then no elements are deleted; the new elements are simply inserted before the one designated by first.
Note that the index is 0-based.
§Examples
use tcl::*;
let list = Obj::from(( "The", "answer", "is", 42 ));
let objs = vec![ "to", "life,", "the", "universe,", "and", "everything:" ].into_iter().map( Obj::from );
list.list_replace( 2, 1, objs ).unwrap();
assert_eq!( list.to_string(), "The answer to life, the universe, and everything: 42" );