utils.h

Overview

This header file declares utility functions primarily focused on time measurement, JSON data handling, and output assistance within the application. It provides platform-independent time retrieval, comparison of JSON strings, and reading JSON test data from files. The file also defines a macro to facilitate JSON token iteration, streamlining JSON parsing operations.

Detailed Descriptions

Preprocessor Directives and Includes

• Platform Compatibility:
  The file ensures compatibility across Windows and POSIX systems by conditionally including platform-specific headers: <windows.h> for Windows and <time.h> for POSIX-compliant systems. It also defines _POSIX_C_SOURCE where necessary to enable POSIX features.

• JSON Dependency:
  It includes "../src/json.h", indicating reliance on a JSON parsing or handling module located relative to this file.

Functions

long long utils_get_time(void);

• Purpose:
  Retrieves the current time in nanoseconds. This function abstracts platform differences to provide a consistent high-resolution timestamp.

• Parameters:
  None.

• Returns:
  A 64-bit integer representing the current time in nanoseconds since an epoch (platform-dependent).

• Usage Example:

  long long start = utils_get_time();
  // ... some operations ...
  long long end = utils_get_time();
  utils_print_time_diff(start, end);
  

• Implementation Detail:
  Internally, this function likely uses QueryPerformanceCounter on Windows and clock_gettime on POSIX systems for high-resolution timing.

void utils_print_time_diff(long long start_ns, long long end_ns);

• Purpose:
  Calculates and prints the time difference between two timestamps, given in nanoseconds.

• Parameters:

  • start_ns: Start time in nanoseconds.

  • end_ns: End time in nanoseconds.

• Returns:
  None.

• Usage Example:

  utils_print_time_diff(start_time, end_time);
  

• Implementation Detail:
  This function computes the difference (end_ns - start_ns) and outputs it, presumably in a human-readable format such as milliseconds or microseconds.

char *utils_get_test_json_data(const char *filename);

• Purpose:
  Reads JSON test data from a file and returns it as a dynamically allocated string.

• Parameters:

  • filename: Path to the JSON file.

• Returns:
  Pointer to a null-terminated string containing the JSON data. The caller is responsible for freeing the allocated memory.

• Usage Example:

  char *json_data = utils_get_test_json_data("test_data.json");
  if (json_data) {
      // use json_data
      free(json_data);
  }
  

• Implementation Detail:
  This function likely opens the specified file, reads its contents entirely, and allocates memory to hold the JSON string.

bool utils_test_json_equal(const char *a, const char *b);

• Purpose:
  Compares two JSON strings for semantic equality.

• Parameters:

  • a: First JSON string.

  • b: Second JSON string.

• Returns:
  true if the JSON data represented by both strings is equal; otherwise, false.

• Usage Example:

  if (utils_test_json_equal(json1, json2)) {
      // JSON data is equivalent
  }
  

• Implementation Detail:
  The function likely parses both JSON strings using the included JSON module and compares their parsed representations, ignoring superficial differences like whitespace or ordering where appropriate.

void utils_output(const char *s);

• Purpose:
  Outputs a given string, potentially for logging or debugging.

• Parameters:

  • s: The string to output.

• Returns:
  None.

• Usage Example:

  utils_output("Operation completed successfully.");
  

• Implementation Detail:
  The function may write the string to standard output or a log file, possibly handling platform-specific output methods.

Macro

NEXT_TOKEN(s)

• Purpose:
  Advances the JSON parser to the next token, returning false if no further tokens are available.

• Parameters:

  • s: A JSON parser state or token pointer (as expected by json_next_token).

• Returns:
  Returns false if json_next_token(s) fails; otherwise, continues execution.

• Usage Example:

  NEXT_TOKEN(state);
  // Continue processing if successful
  

• Implementation Detail:
  This macro wraps a call to json_next_token, providing concise error handling for token iteration.

Interaction with Other System Components

• The file depends directly on the JSON parser module denoted by "../src/json.h", indicating that JSON parsing and token management are external responsibilities.

• It abstracts platform-specific time handling, allowing other components to use a consistent interface for timing without worrying about OS differences.

• The JSON comparison and file reading utilities facilitate testing and validation workflows, likely used in unit tests or during development.

• The output utility provides a centralized method for string output, which could integrate with logging systems or debugging tools.

Visual Diagram of utils.h Structure

flowchart TD
A[utils_get_time] --> B[utils_print_time_diff]
A --> C[utils_get_test_json_data]
C --> D[utils_test_json_equal]
D --> E[utils_output]
F[NEXT_TOKEN macro] -->|calls| G[json_next_token]
style A fill:#f9f,stroke:#333,stroke-width:1px
style B fill:#ccf,stroke:#333,stroke-width:1px
style C fill:#cfc,stroke:#333,stroke-width:1px
style D fill:#fcf,stroke:#333,stroke-width:1px
style E fill:#cff,stroke:#333,stroke-width:1px
style F fill:#ffc,stroke:#333,stroke-width:1px
style G fill:#eee,stroke:#333,stroke-width:1px

This flowchart illustrates the main functions and their relationships, showing how the JSON token macro depends on the external json_next_token function and how time-related functions relate to each other.