Dataset

Danger

⚠️ API NOT STABLE - DO NOT USE ⚠️

This API documentation is for DEVELOPMENT PURPOSES ONLY.

Functions shown may NOT WORK or may CHANGE without notice
Memory management is NOT GUARANTEED to be safe
DO NOT build applications with these functions

This documentation exists only to guide ongoing development work.

Core API for the Dataset type and its serialization.

A Dataset bundles:

a list of dimensions (with optional custom ordering),
one or more dependent variables (each potentially externalized),
string tags, title & description,
an optional focus datum and metadata dictionary.

You can create one in‐memory, serialize it to a deep dictionary (for testing or round‐trip), and read/write full CSDF/CSDFE files with Export/Import.

Accessors & Mutators

OCMutableArrayRef DatasetGetDimensions(DatasetRef ds): Get mutable array of Dimensions.

bool DatasetSetDimensions(DatasetRef ds, OCMutableArrayRef dims): Replace the dimensions array (must match existing DVs).

OCMutableIndexArrayRef DatasetGetDimensionPrecedence(DatasetRef ds): Get mutable index array for dimension precedence.

bool DatasetSetDimensionPrecedence(DatasetRef ds, OCMutableIndexArrayRef order): Replace the dimension precedence ordering.

OCMutableArrayRef DatasetGetDependentVariables(DatasetRef ds): Get mutable array of DependentVariable.

bool DatasetSetDependentVariables(DatasetRef ds, OCMutableArrayRef dvs): Replace the dependent-variables list.

DependentVariableRef DatasetGetDependentVariableAtIndex(DatasetRef ds, OCIndex index): Fetch the i-th dependent variable.

OCMutableArrayRef DatasetGetTags(DatasetRef ds): Get/replace tags.

bool DatasetSetTags(DatasetRef ds, OCMutableArrayRef tags)

OCStringRef DatasetGetDescription(DatasetRef ds): Get/replace description.

bool DatasetSetDescription(DatasetRef ds, OCStringRef desc)

OCStringRef DatasetGetTitle(DatasetRef ds): Get/replace title.

bool DatasetSetTitle(DatasetRef ds, OCStringRef title)

DatumRef DatasetGetFocus(DatasetRef ds): Get/replace focus Datum.

bool DatasetSetFocus(DatasetRef ds, DatumRef focus)

DatumRef DatasetGetPreviousFocus(DatasetRef ds): Get/replace previous focus Datum.

bool DatasetSetPreviousFocus(DatasetRef ds, DatumRef previousFocus)

OCDictionaryRef DatasetGetApplicationMetaData(DatasetRef ds): Get/replace arbitrary metadata dictionary.

bool DatasetSetApplicationMetaData(DatasetRef ds, OCDictionaryRef md)

CSDM-1.0 Fields

OCStringRef DatasetGetVersion(DatasetRef ds): Dataset version string (always “1.0”).

bool DatasetSetVersion(DatasetRef ds, OCStringRef version): Override version (rarely needed).

OCStringRef DatasetGetTimestamp(DatasetRef ds): ISO-8601 timestamp of serialization.

bool DatasetSetTimestamp(DatasetRef ds, OCStringRef timestamp): Override timestamp (rarely needed).

GeographicCoordinateRef DatasetGetGeographicCoordinate(DatasetRef ds): Geographic coordinate, if set.

bool DatasetSetGeographicCoordinate(DatasetRef ds, GeographicCoordinateRef gc): Override geographic coordinate.

bool DatasetGetReadOnly(DatasetRef ds): Read-only flag.

bool DatasetSetReadOnly(DatasetRef ds, bool readOnly): Set or clear read-only.

Typedefs

typedef struct impl_Dataset *DatasetRef: Opaque handle for a Dataset object.

Functions

OCTypeID DatasetGetTypeID(void): Return the unique OCTypeID for Dataset.

DatasetRef DatasetCreate(OCArrayRef dimensions, OCIndexArrayRef dimensionPrecedence, OCArrayRef dependentVariables, OCArrayRef tags, OCStringRef description, OCStringRef title, DatumRef focus, DatumRef previousFocus, OCDictionaryRef metaData, OCStringRef *outError)

Construct a new Dataset.

Performs basic validation:

at least one dependent variable,
each DV’s length matches the product of all dimension sizes,
dimensions themselves have valid types.

Parameters:

dimensions – Array of DimensionRef (may be NULL ⇒ scalar DV only).
dimensionPrecedence – Optional index‐ordering array (NULL ⇒ natural order).
dependentVariables – Array of DependentVariableRef (must not be empty).
tags – Array of OCStringRef tags (may be NULL).
description – Short description (may be NULL or empty).
title – Human-readable title (may be NULL or empty).
focus – Optional DatumRef focus (may be NULL).
previousFocus – Optional previous focus (may be NULL).
metaData – Arbitrary key/value metadata (may be NULL).
outError – [out] If non-NULL and creation fails, set to an OCStringRef describing the validation or allocation error.

Returns:

Newly allocated DatasetRef on success, or NULL on failure.

DatasetRef DatasetCreateMinimal(OCArrayRef dimensions, OCArrayRef dependentVariables, OCStringRef *outError)

Create a minimal Dataset with only dimensions and dependent variables.

This is a simplified version of DatasetCreate that only requires the essential components: dimensions and dependent variables. All other fields are set to sensible defaults (empty strings, NULL, etc.).

Parameters:

dimensions – Array of DimensionRef (may be NULL for scalar data).
dependentVariables – Array of DependentVariableRef (must not be empty).
outError – [out] If non-NULL and creation fails, set to an OCStringRef describing the validation or allocation error.

Returns:

Newly allocated DatasetRef on success, or NULL on failure.

DatasetRef DatasetCreateEmpty(OCStringRef *outError)

Helper: Create an empty Dataset (all fields NULL except outError).

Parameters:

outError – [out] If non-NULL and creation fails, set to error string.

Returns:

Newly allocated DatasetRef on success, or NULL on failure.

DatasetRef DatasetCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError)

Rebuild a Dataset from a deep‐copied dictionary.

Parameters:

dict – Dictionary produced by DatasetCopyAsDictionary().
outError – On error, set to an OCStringRef describing the problem.

Returns:

DatasetRef or NULL on parse/factory failure.

DatasetRef DatasetCreateFromJSON(cJSON *json, OCStringRef *outError)

Create a Dataset from a cJSON object.

This is the preferred method for creating Datasets from JSON data, providing better performance and error handling than dictionary conversion.

Parameters:

json – cJSON object with dataset definition.
outError – On error, set to a brief description string.

Returns:

DatasetRef or NULL on parse/factory failure.

OCDictionaryRef DatasetCopyAsDictionary(DatasetRef ds)

Serialize a Dataset into a deep‐copyable dictionary.

Use this for tests, round-trip, or JSON conversion via cJSON.

Parameters:

ds – DatasetRef to serialize.

Returns:

An OCDictionaryRef you must OCRelease() when done.

cJSON *DatasetCopyAsJSON(DatasetRef ds, bool typed, OCStringRef *outError)

Convert a DatasetRef to cJSON representation.

Parameters:

ds – The Dataset to convert.
typed – Whether to include type information in the JSON.

Returns:

cJSON object or NULL on error.

DatasetRef DatasetCreateCopy(DatasetRef ds)

Convenience: deep-copy via CopyAsDictionary + CreateFromDictionary.

Parameters:

ds – Source DatasetRef (must not be NULL).

Returns:

New DatasetRef copy, or NULL if any error.

bool DatasetExport(DatasetRef ds, const char *json_path, const char *binary_dir, OCStringRef *outError)

Write a Dataset to disk.

Serializes the Dataset to JSON and writes to json_path (must end in “.csdf” if no externals, or “.csdfe” if any external DVs),
Writes each external DV’s raw blob under binary_dir/….

Parameters:

ds – Dataset to export.
json_path – Full path to JSON file (.csdf/.csdfe).
binary_dir – Directory under which to write external‐data files. If NULL, the directory containing json_path is used.
outError – On error, set to a brief OCStringRef.

Returns:

true on success, false on failure (and *outError set).

DatasetRef DatasetCreateWithImport(const char *json_path, const char *binary_dir, OCStringRef *outError)

Read a Dataset + externals back from disk.

Parses the JSON file at json_path,
Constructs the Dataset object,
Loads any external blobs from binary_dir/….

Parameters:

json_path – Path to JSON (.csdf/.csdfe).
binary_dir – Directory where external-data files live.
outError – On error, set to a brief OCStringRef.

Returns:

Newly allocated DatasetRef, or NULL on failure.

DependentVariableRef DatasetAddEmptyDependentVariable(DatasetRef theDataset, OCStringRef quantityType, OCNumberType elementType, OCIndex size)

group IO

Read & write full Dataset + external blobs.

Typedefs

typedef struct impl_Dataset *DatasetRef: Opaque handle for a Dataset object.

Functions

bool DatasetExport(DatasetRef ds, const char *json_path, const char *binary_dir, OCStringRef *outError)

Write a Dataset to disk.

Serializes the Dataset to JSON and writes to json_path (must end in “.csdf” if no externals, or “.csdfe” if any external DVs),
Writes each external DV’s raw blob under binary_dir/….

Parameters:

ds – Dataset to export.
json_path – Full path to JSON file (.csdf/.csdfe).
binary_dir – Directory under which to write external‐data files. If NULL, the directory containing json_path is used.
outError – On error, set to a brief OCStringRef.

Returns:

true on success, false on failure (and *outError set).

DatasetRef DatasetCreateWithImport(const char *json_path, const char *binary_dir, OCStringRef *outError)

Read a Dataset + externals back from disk.

Parses the JSON file at json_path,
Constructs the Dataset object,
Loads any external blobs from binary_dir/….

Parameters:

json_path – Path to JSON (.csdf/.csdfe).
binary_dir – Directory where external-data files live.
outError – On error, set to a brief OCStringRef.

Returns:

Newly allocated DatasetRef, or NULL on failure.