Structured Data Utilities

/**
 * Returns a Struct containing the single key-value pair.
 * 
 * @param k1 Key for the first field
 * @param v1 Value for the first field
 * @return Struct containing the specified key-value pair
 */
public static Struct of(String k1, Value v1);

/**
 * Returns a Struct containing the two key-value pairs.
 * Providing duplicate keys results in undefined behavior.
 * 
 * @param k1 Key for the first field
 * @param v1 Value for the first field
 * @param k2 Key for the second field
 * @param v2 Value for the second field
 * @return Struct containing the specified key-value pairs
 */
public static Struct of(String k1, Value v1, String k2, Value v2);

/**
 * Returns a Struct containing the three key-value pairs.
 * Providing duplicate keys results in undefined behavior.
 * 
 * @param k1 Key for the first field
 * @param v1 Value for the first field
 * @param k2 Key for the second field
 * @param v2 Value for the second field
 * @param k3 Key for the third field
 * @param v3 Value for the third field
 * @return Struct containing the specified key-value pairs
 */
public static Struct of(String k1, Value v1, String k2, Value v2, String k3, Value v3);

/**
 * Returns a Value representing null.
 * 
 * @return Value with null_value set
 */
public static Value ofNull();

/**
 * Returns a Value with boolean value.
 * 
 * @param value Boolean value to wrap
 * @return Value with bool_value set to the specified boolean
 */
public static Value of(boolean value);

/**
 * Returns a Value with number value.
 * 
 * @param value Double value to wrap
 * @return Value with number_value set to the specified double
 */
public static Value of(double value);

/**
 * Returns a Value with string value.
 * 
 * @param value String value to wrap
 * @return Value with string_value set to the specified string
 */
public static Value of(String value);

/**
 * Returns a Value with struct value.
 * 
 * @param value Struct to wrap
 * @return Value with struct_value set to the specified Struct
 */
public static Value of(Struct value);

/**
 * Returns a Value with list value.
 * 
 * @param value ListValue to wrap
 * @return Value with list_value set to the specified ListValue
 */
public static Value of(ListValue value);

/**
 * Returns a Value with ListValue created from the iterable.
 * Creates a ListValue by appending all elements from the iterable.
 * 
 * @param values Iterable of Value objects to include in the list
 * @return Value with list_value containing all specified values
 */
public static Value of(Iterable<Value> values);

import com.google.protobuf.util.Structs;
import com.google.protobuf.util.Values;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import com.google.protobuf.ListValue;
import java.util.Arrays;

// Create simple Value objects
Value nullValue = Values.ofNull();
Value boolValue = Values.of(true);
Value numberValue = Values.of(42.5);
Value stringValue = Values.of("hello world");

// Create a simple Struct with one field
Struct simpleStruct = Structs.of("name", Values.of("Alice"));

// Create Struct with multiple fields
Struct userStruct = Structs.of(
    "name", Values.of("Bob"),
    "age", Values.of(30),
    "active", Values.of(true)
);

// Create more complex nested structures
Value addressValue = Values.of(Structs.of(
    "street", Values.of("123 Main St"),
    "city", Values.of("Anytown"),
    "zipcode", Values.of("12345")
));

Struct complexStruct = Structs.of(
    "user", Values.of(userStruct),
    "address", addressValue,
    "tags", Values.of(Arrays.asList(
        Values.of("premium"),
        Values.of("verified"),
        Values.of("new")
    ))
);

// Create ListValue and wrap in Value
ListValue numberList = ListValue.newBuilder()
    .addValues(Values.of(1))
    .addValues(Values.of(2))
    .addValues(Values.of(3))
    .build();
Value listValue = Values.of(numberList);

// Create Value from iterable
Value iterableValue = Values.of(Arrays.asList(
    Values.of("first"),
    Values.of("second"),
    Values.of("third")
));


// Building complex JSON-like structures
Struct apiResponse = Structs.of(
    "success", Values.of(true),
    "data", Values.of(Structs.of(
        "users", Values.of(Arrays.asList(
            Values.of(Structs.of("id", Values.of(1), "name", Values.of("Alice"))),
            Values.of(Structs.of("id", Values.of(2), "name", Values.of("Bob")))
        )),
        "total", Values.of(2)
    )),
    "metadata", Values.of(Structs.of(
        "timestamp", Values.of("2024-01-15T10:30:00Z"),
        "version", Values.of("1.0.0")
    ))
);

// Convert to JSON using JsonFormat for verification
// This demonstrates interoperability with JSON utilities
import com.google.protobuf.util.JsonFormat;

try {
    String jsonString = JsonFormat.printer().print(complexStruct);
    System.out.println("Struct as JSON: " + jsonString);
} catch (Exception e) {
    System.err.println("JSON conversion error: " + e.getMessage());
}

import com.google.protobuf.util.JsonFormat;
import com.google.protobuf.util.Structs;
import com.google.protobuf.util.Values;

// Create structured data
Struct data = Structs.of(
    "message", Values.of("Hello, world!"),
    "priority", Values.of(1),
    "enabled", Values.of(true),
    "metadata", Values.of(Structs.of(
        "source", Values.of("api"),
        "timestamp", Values.of("2024-01-15T10:30:00Z")
    ))
);

// Convert to JSON
JsonFormat.Printer printer = JsonFormat.printer();
String json = printer.print(data);

// Parse back from JSON
JsonFormat.Parser parser = JsonFormat.parser();
Struct.Builder builder = Struct.newBuilder();
parser.merge(json, builder);
Struct parsed = builder.build();