Using Tags

Learn how to use tags and save them in a file.

In order to represent data, ODS uses Tags. In order to save data to a file/memory, you need to create a tag to wrap that data.

Tag Types

A tag for every primary data type exists (plus a few advanced one.) While similar for the most part, there can be some variation in the name of tags for each implementation of ODS. Below is a table with all of the names.

Java	C#	Rust
StringTag	StringTag	StringTag
IntegerTag	IntegerTag	IntegerTag
FloatTag	FloatTag	FloatTag
DoubleTag	DoubleTag	DoubleTag
ShortTag	ShortTag	ShortTag
LongTag	LongTag	LongTag
ByteTag	ByteTag	ByteTag
ListTag	ListTag	VectorTag
MapTag	DictionaryTag	N/A
ObjectTag	ObjectTag	ObjectTag
Compressed Object	Compressed Object	N/A

Creating a Tag

Creating a tag is a very simple process. All you need to do is construct that tag and provide it with the name and the value of the tag.

Java

import me.ryandw11.ods.tags;

StringTag stringTag = new StringTag("MyString", "My Value!");

C#

using ODS.Tags;

StringTag stringTag = new StringTag("MyString", "My Value!");

Rust

Names like "StringTag" are just a type definitions in the Rust implementation. To understand how Rust Tags work internally, please view the Rust specific documentation. Note: This information is not important to know to use the library

use object_data_structure::tags::general::{StringTag}

let mut string_tag: StringTag = StringTag::new("MyString".to_string(), "My Value!".to_string());

The code above will create a new StringTag for you to use. All of the other tags have the exact same syntax for creating them. It is the name followed by the value.

Saving Tags

ODS allows you to save a list of tags to a file (or the memory buffer). When using the save method, the file or buffer is overwritten causing all data already there to be deleted. (If the file does not exist, ODS will automatically create it.)

Java

 ObjectDataStructure ods = new ObjectDataStructure(new File("test.ods"));
 
 List<Tag<?>> tags = new ArrayList<>();
 StringTag stringTag = new StringTag("MyString", "My Value!");
 tags.add(stringTag);
 
 ods.save(tags);

C#

ObjectDataStructure ods = new ObjectDataStructure();

List<ITag> tags = new List<ITag>();
StringTag stringTag = new StringTag("MyString", "My Value!");
tags.Add(stringTag);

ods.Save(tags);

Rust

Rust currently does not have an implementation for the Save method. Please use the Append method instead (see below).

Appending Tags

Overwriting the data in a file/buffer is often not very convenient, that is why ODS offers the ability to append tags to the end of the file/buffer.

Java

ObjectDataStructure ods = new ObjectDataStructure(new File("test.ods"));
 
StringTag stringTag = new StringTag("MyString", "My Value!");
 
ods.append(stringTag);

C#

ObjectDataStructure ods = new ObjectDataStructure();

StringTag stringTag = new StringTag("MyString", "My Value!");

ods.Append(tags);

Rust

let mut ods = ObjectDataStructure::new_file(PathBuf::from("./file.ods"));

let mut string_tag: StringTag = StringTag::new("MyString".to_string(), 
    "My Value!".to_string());

ods.append(string_tag);

You can also use appendAll to append a list of tags to the end of the file/buffer.

Additional Notes

Utility methods and macros exist in the different implementations to make it easier (to an extent) to create tags.

Java

In Java you can use the ODS utility class to wrap supported data types into Tags. (This can also serialize classes into ObjectTags. See the serialization section for more info).

StringTag stringTag = ODS.wrap("MyString", "My Value!");
IntTag intTag = ODS.wrap("MyInt", 20);

C#

In C# you can use the ODSUtil utility class to wrap supported data types into Tags. (This can also serialize classes into ObjectTags. See the serialization section for more info).

Due to some of the limitations of C# generics, this method is not as useful as it's Java counterpart as you must downcast it from an ITag. (This will work fine if feeding it into an ITag list though.)

StringTag stringTag = (StringTag) ODSUtil.Wrap("MyString", "My Value!");
IntTag intTag = (IntTag) ODSUtil.Wrap("MyInt", 20);

Rust

In Rust, a utility macro exists for the creation of Tags in Rust. (Be certain you have #[macro_use] above the extern statement for ODS.)

let string_tag: StringTag = tag![StringTag, "MyString", "My Value!".to_string()];
let int_tag: IntTag = tag![IntTag, "MyInt", 20];

Note: The tag macro will automatically convert the name of the tag from str& to a String for you.

Unwrap utility methods also exist. More about them are covered in the get section.

The next few sub-sections will teach you more about the special tags.