seasonder_readCSField: Read a CSField from a Binary Connection

In SeaSondeR: Radial Metrics from SeaSonde HF-Radar Data

Read a CSField from a Binary Connection

Description

This function reads specific data types from a binary connection, supporting various types including integer, float, double, complex, and strings.

Usage

seasonder_readCSField(con, type, endian = "big")

Arguments

con	A connection object to a binary file.
type	A character string identifying the type of data to read.
endian	A character string indicating the byte order. Options are "big" and "little" (default is "big").

Value

The value obtained from reading the CSField according to the specified type.

Supported Data Types

This function provides support for reading a variety of data types from a binary connection. The following data types are recognized and can be used for the type argument:

CharN

Reads N characters from the connection where N is a positive integer. For example, Char5 would read five characters.

UInt8

Reads an 8-bit unsigned integer.

SInt8

Reads an 8-bit signed integer.

UInt16

Reads a 16-bit unsigned integer.

SInt16

Reads a 16-bit signed integer.

UInt32

Reads a 32-bit unsigned integer.

SInt32

Reads a 32-bit signed integer.

Float

Reads a single-precision floating-point number.

Double

Reads a double-precision floating-point number.

UInt64

Reads a 64-bit unsigned integer.

SInt64

Reads a 64-bit signed integer.

Complex

Reads a complex number by separately reading the real and imaginary parts, which are each represented as double-precision floating-point numbers.

String

Reads a null-terminated string.

If the provided type does not match any of the supported data types, the function raises an error.

Condition Management

This function utilizes the rlang package to manage conditions and provide detailed and structured condition messages:

Condition Classes:

• seasonder_cs_field_reading_error: General error related to reading a CSField from the binary connection.

• seasonder_cs_field_skipped: Condition that indicates a CSField was skipped due to a reading error.

Condition Cases:

• Connection is not open.

• Error while reading value from connection.

• Read value of length 0 from connection (likely reached end of file).

• Unrecognized data type specified.

Restart Options: This function provides a structured mechanism to recover from errors during its execution using the rlang::withRestarts function. The following restart option is available:

seasonder_skip_cs_field(cond, value)

This allows for the graceful handling of reading errors. If this restart is invoked, the function will log an error message indicating that a specific CSField reading was skipped and will return the value specified. The restart takes two arguments: cond (the condition or error that occurred) and value (the value to return if this CSField reading is skipped). To invoke this restart during a condition or error, you can use the helper function seasonder_skip_cs_field(cond, value).

• Usage: In a custom condition handler, you can call seasonder_skip_cs_field(cond, yourDesiredReturnValue) to trigger this restart and skip the current CSField reading.

• Effect: If invoked, the function logs an error message detailing the reason for skipping, and then returns the value specified in the restart function call.

See Also

seasonder_skip_cs_field, seasonder_raw_to_int

SeaSondeR documentation built on June 8, 2025, 10:50 a.m.