Skip to content

Commit d7419a3

Browse files
author
Devdutt Shenoi
committed
doc: code comments
1 parent b717b52 commit d7419a3

File tree

1 file changed

+34
-11
lines changed

1 file changed

+34
-11
lines changed

src/utils/json/flatten.rs

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ pub enum JsonFlattenError {
4747
NonObjectInArray,
4848
}
4949

50+
// Recursively flattens JSON objects and arrays, e.g. with the separator `.`, starting from the TOP
51+
// `{"key": "value", "nested_key": {"key":"value"}}` becomes `{"key": "value", "nested_key.key": "value"}`
5052
pub fn flatten(
5153
nested_value: &mut Value,
5254
separator: &str,
@@ -67,6 +69,7 @@ pub fn flatten(
6769
}
6870
Value::Array(arr) => {
6971
for nested_value in arr {
72+
// Recursively flatten each element, ONLY in the TOP array
7073
flatten(
7174
nested_value,
7275
separator,
@@ -83,6 +86,19 @@ pub fn flatten(
8386
Ok(())
8487
}
8588

89+
// Checks if a JSON value is null or empty
90+
fn is_null_or_empty(value: &Value) -> bool {
91+
match value {
92+
Value::Null => true,
93+
Value::Object(o) if o.is_empty() => true,
94+
Value::Array(a) if a.is_empty() => true,
95+
Value::String(s) if s.is_empty() => true,
96+
_ => false,
97+
}
98+
}
99+
100+
// Validates the presence and content of custom partition fields
101+
// that it is not null, empty, or a floating-point number
86102
pub fn validate_custom_partition(
87103
value: &Map<String, Value>,
88104
custom_partition: Option<&String>,
@@ -100,16 +116,6 @@ pub fn validate_custom_partition(
100116
));
101117
};
102118

103-
fn is_null_or_empty(value: &Value) -> bool {
104-
match value {
105-
Value::Null => true,
106-
Value::Object(o) if o.is_empty() => true,
107-
Value::Array(a) if a.is_empty() => true,
108-
Value::String(s) if s.is_empty() => true,
109-
_ => false,
110-
}
111-
}
112-
113119
if is_null_or_empty(field_value) {
114120
return Err(JsonFlattenError::FieldEmptyOrNull(trimmed_field.to_owned()));
115121
}
@@ -124,6 +130,8 @@ pub fn validate_custom_partition(
124130
Ok(())
125131
}
126132

133+
// Validates time partitioning constraints, checking if a timestamp is a string
134+
// that can be parsed as datetime within the configured time limit
127135
pub fn validate_time_partition(
128136
value: &Map<String, Value>,
129137
time_partition: Option<&String>,
@@ -160,6 +168,8 @@ pub fn validate_time_partition(
160168
}
161169
}
162170

171+
// Flattens starting from only object types at TOP, e.g. with the parent_key `root` and separator `_`
172+
// `{ "a": { "b": 1, c: { "d": 2 } } }` becomes `{"root_a_b":1,"root_a_c_d":2}`
163173
pub fn flatten_with_parent_prefix(
164174
nested_value: &mut Value,
165175
prefix: &str,
@@ -176,7 +186,8 @@ pub fn flatten_with_parent_prefix(
176186
Ok(())
177187
}
178188

179-
pub fn flatten_object(
189+
// Flattens a nested JSON Object/Map into another target Map
190+
fn flatten_object(
180191
output_map: &mut Map<String, Value>,
181192
parent_key: Option<&str>,
182193
nested_map: &mut Map<String, Value>,
@@ -203,6 +214,7 @@ pub fn flatten_object(
203214
Ok(())
204215
}
205216

217+
// Flattens a nested JSON Array into the parent Map
206218
pub fn flatten_array_objects(
207219
output_map: &mut Map<String, Value>,
208220
parent_key: &str,
@@ -248,6 +260,16 @@ pub fn flatten_array_objects(
248260
Ok(())
249261
}
250262

263+
/// Recursively flattens a JSON value.
264+
/// - If the value is an array, it flattens all elements of the array.
265+
/// - If the value is an object, it flattens all nested objects and arrays.
266+
/// - Otherwise, it returns the value itself in a vector.
267+
///
268+
/// Examples:
269+
/// 1. `{"a": 1}` ~> `[{"a": 1}]`
270+
/// 2. `[{"a": 1}, {"b": 2}]` ~> `[{"a": 1}, {"b": 2}]`
271+
/// 3. `[{"a": [{"b": 1}, {"c": 2}]}]` ~> `[{"a": {"b": 1)}}, {"a": {"c": 2)}}]`
272+
/// 3. `{"a": [{"b": 1}, {"c": 2}], "d": {"e": 4}}` ~> `[{"a": {"b":1}, "d": {"e":4}}, {"a": {"c":2}, "d": {"e":4}}]`
251273
pub fn flatten_json(value: &Value) -> Vec<Value> {
252274
match value {
253275
Value::Array(arr) => arr.iter().flat_map(flatten_json).collect(),
@@ -290,6 +312,7 @@ pub fn flatten_json(value: &Value) -> Vec<Value> {
290312
}
291313
}
292314

315+
// Converts a Vector of values into a `Value::Array`, as long as all of them are objects
293316
pub fn convert_to_array(flattened: Vec<Value>) -> Result<Value, JsonFlattenError> {
294317
let mut result = Vec::new();
295318
for item in flattened {

0 commit comments

Comments
 (0)