1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

use crate::raw_symbol_token_ref::AsRawSymbolTokenRef;
use crate::result::IonResult;
use crate::types::{Decimal, Int, IonType, Timestamp};

/**
 * This trait captures the format-agnostic encoding functionality needed to write native Rust types
 * to a stream as Ion values.
 */
pub trait IonWriter {
    /// The type to which the implementor writes its data. This may be a file, a buffer, etc.
    type Output;

    /// Returns the (major, minor) version of the Ion stream being written. If ion_version is called
    /// before an Ion Version Marker has been emitted, the version (1, 0) will be returned.
    fn ion_version(&self) -> (u8, u8);

    /// Writes an Ion version marker to the output stream.
    fn write_ion_version_marker(&mut self, major: u8, minor: u8) -> IonResult<()>;

    /// Returns `true` if this RawWriter supports writing field names, annotations, and
    /// symbol values directly as text; otherwise, returns `false`.
    ///
    /// If this method returns `false`, passing a [crate::RawSymbolToken::Text] to the
    /// [Self::set_annotations], [Self::set_field_name], or [Self::write_symbol] methods may result
    /// in a panic.
    fn supports_text_symbol_tokens(&self) -> bool;

    /// Sets a list of annotations that will be applied to the next value that is written.
    fn set_annotations<I, A>(&mut self, annotations: I)
    where
        A: AsRawSymbolTokenRef,
        I: IntoIterator<Item = A>;

    /// Writes an Ion `null` with the specified type to the output stream.
    /// To write an untyped `null` (which is equivalent to `null.null`), pass [IonType::Null].
    fn write_null(&mut self, ion_type: IonType) -> IonResult<()>;

    /// Writes an Ion `boolean` with the specified value to the output stream.
    fn write_bool(&mut self, value: bool) -> IonResult<()>;

    /// Writes an Ion `integer` with the specified value to the output stream.
    fn write_i64(&mut self, value: i64) -> IonResult<()>;

    /// Writes an Ion `integer` with the specified value to the output stream.
    fn write_int(&mut self, value: &Int) -> IonResult<()>;

    /// Writes an Ion `float` with the specified value to the output stream.
    fn write_f32(&mut self, value: f32) -> IonResult<()>;

    /// Writes an Ion `float` with the specified value to the output stream.
    fn write_f64(&mut self, value: f64) -> IonResult<()>;

    /// Writes an Ion `decimal` with the specified value to the output stream.
    fn write_decimal(&mut self, value: &Decimal) -> IonResult<()>;

    /// Writes an Ion `timestamp` with the specified value to the output stream.
    fn write_timestamp(&mut self, value: &Timestamp) -> IonResult<()>;

    /// Writes an Ion `symbol` with the specified value to the output stream.
    fn write_symbol<A: AsRawSymbolTokenRef>(&mut self, value: A) -> IonResult<()>;

    /// Writes an Ion `string` with the specified value to the output stream.
    fn write_string<A: AsRef<str>>(&mut self, value: A) -> IonResult<()>;

    /// Writes an Ion `clob` with the specified value to the output stream.
    fn write_clob<A: AsRef<[u8]>>(&mut self, value: A) -> IonResult<()>;

    /// Writes an Ion `blob` with the specified value to the output stream.
    fn write_blob<A: AsRef<[u8]>>(&mut self, value: A) -> IonResult<()>;

    /// Starts a new Ion container with the specified type.
    /// The only valid IonType values are:
    /// * [IonType::List]
    /// * [IonType::SExp]
    /// * [IonType::Struct]
    /// Passing any other IonType will result in an `Err`.
    fn step_in(&mut self, container_type: IonType) -> IonResult<()>;

    /// Sets the current field name to `name`. If the TextWriter is currently positioned inside
    /// of a struct, the field name will be written before the next value. Otherwise, it will be
    /// ignored.
    fn set_field_name<A: AsRawSymbolTokenRef>(&mut self, name: A);

    /// If the writer is positioned at the top level, returns `None`. Otherwise, returns
    /// `Some(_)` with the parent container's [IonType].
    fn parent_type(&self) -> Option<IonType>;

    /// Returns the number of containers that the writer has stepped into without subsequently
    /// stepping out.
    fn depth(&self) -> usize;

    /// Ends the current container. If the writer is not currently positioned within a container,
    /// calling this method will result in an `Err`.
    fn step_out(&mut self) -> IonResult<()>;

    /// Causes any buffered data to be written to the underlying io::Write implementation.
    /// This method can only be called when the writer is at the top level.
    fn flush(&mut self) -> IonResult<()>;

    /// Returns a reference to the writer's output.
    ///
    /// This method can be used to inspect the Ion data that the writer has produced without having
    /// to first drop the writer.
    /// ```
    /// use ion_rs::element::Element;
    /// use ion_rs::{IonResult, IonWriter, TextWriter, TextWriterBuilder};
    /// # fn roundtrip() -> IonResult<()> {
    /// // Set up our output buffer
    /// let mut buffer: Vec<u8> = Vec::new();
    /// // Construct a writer that will serialize values to the buffer
    /// let mut writer = TextWriterBuilder::default().build(&mut buffer)?;
    /// // Serialize some data
    /// writer.write_string("hello")?;
    /// writer.flush()?;
    /// // Read the data back from the output buffer
    /// let output_element = Element::read_one(writer.output())?;
    /// // Confirm that it matches the input data
    /// assert_eq!(Element::from("hello"), output_element);
    /// # Ok(())
    /// # }
    /// # roundtrip().unwrap();
    /// ```
    fn output(&self) -> &Self::Output;

    /// Returns a mutable reference to the writer's output.
    ///
    /// Modifying the underlying sink is an inherently risky operation and can result in unexpected
    /// behavior or invalid data. It is not recommended for most use cases.
    fn output_mut(&mut self) -> &mut Self::Output;
}