\[ \newcommand{\ListType}{{\text{List}}} \newcommand{\ListEmpty}{{\left[\right]}} \newcommand{\ListLength}[1]{{\ell\left(#1\right)}} \newcommand{\ListAt}[2]{{{#1}_{#2}}} \]
Home

Michael Heilmann's Arcadia Ring 2

This is the documentation for Michael Heilmann's Arcadia Ring 2. Arcadia Ring 2 facilitates the creation of C programs - in particular interpreters - that are portable, maintainable, as well as safe. Arcadia Ring 2 is available at michaelheilmann.com/Arcadia/Ring2.

Features:

Files

You can find the sources of Arcadia Ring 2 in my GitHub repository https://github.com/michaelheilmann/arcadia. The subdirectory of Arcadia Ring 2 in the repository is here https://github.com/michaelheilmann/arcadia/tree/main/Runtime/Ring2.

Arcadia Ring 2 supports various platforms (including but not restricted to Windows, Linux, and many more), however, we currently only officially support Windows. For instructions on how to build, test, and use Arcadia Ring 1, refer to README.md in the root folder of the repository.

Further References

Arcadia Ring 2 relies on Arcadia Ring 1 and Arcadia ARMS.

String extensions

The functions in this section extend Arcadia_String, Arcadia_StringBuilder, and Arcadia_ByteArrayBuilder with conversions to and from C++ (C) values and null-terminated C-strings.

Arcadia_String_createFromCxxInt

Arcadia_String*
Arcadia_String_createFromCxxInt
  (
    Arcadia_Thread* thread,
    int x
  ) Create a string from a C++ int value.

Parameters

A pointer to the Arcadia_Thread object.
int x
The value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_String_toCxxInt

int
Arcadia_String_toCxxInt
  (
    Arcadia_Thread* thread,
    Arcadia_String* self
  ) Get the C++ int value of this string.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.

Return value

The C++ int value of this string.

Errors

Arcadia_Status_ConversionFailed
This string does not hold the decimal representation of an integer, or the integer is outside the range of a C++ int.

Arcadia_String_createFromCxxString

Arcadia_String*
Arcadia_String_createFromCxxString
  (
    Arcadia_Thread* thread,
    const char *x
  ) Create a string from a null-terminated C-string.

Parameters

A pointer to the Arcadia_Thread object.
const char *x
An array of Bytes. Must be a null pointer or a pointer to the first Byte of a null-terminated sequence of Bytes.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_Status_ArgumentValueInvalid
x is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_StringBuilder_insertBackCxxInt

void
Arcadia_StringBuilder_insertBackCxxInt
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    int x
  ) Insert the string representation of a C++ int value at the back of this string buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder* self
A pointer to this string buffer.
int x
The value.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_StringBuilder_insertBackCxxString

void
Arcadia_StringBuilder_insertBackCxxString
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    const char *x
  ) Insert a null-terminated C-string at the back of this string buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder* self
A pointer to this string buffer.
const char *x
An array of Bytes. Must be a null pointer or a pointer to the first Byte of a null-terminated sequence of Bytes.

Errors

Arcadia_Status_ArgumentValueInvalid
self or x is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_StringBuilder_insertFrontString

void
Arcadia_StringBuilder_insertFrontString
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    Arcadia_String* x
  ) Insert a string at the front of this string buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder* self
A pointer to this string buffer.
Arcadia_String* x
A pointer to the string to insert.

Errors

Arcadia_Status_ArgumentValueInvalid
self or x is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_StringBuilder_insertBackString

void
Arcadia_StringBuilder_insertBackString
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    Arcadia_String* x
  ) Insert a string at the back of this string buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder* self
A pointer to this string buffer.
Arcadia_String* x
A pointer to the string to insert.

Errors

Arcadia_Status_ArgumentValueInvalid
self or x is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_String_insertByteBuffer

void
Arcadia_String_insertByteBuffer
  (
    Arcadia_Thread* thread,
    Arcadia_String* self,
    Arcadia_SizeValue index,
    Arcadia_ByteArrayBuilder* target
  ) Insert the Bytes of this string into the Byte buffer at the specified index.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.
Arcadia_SizeValue index
The index at which to insert the Bytes. Must be within the bounds of [0,n) where n is the size, in Bytes, of the Byte buffer.
Arcadia_ByteArrayBuilder* target
A pointer to the Byte buffer.

Errors

Arcadia_Status_ArgumentValueInvalid
self or target is a null pointer, or index is outside the bounds of the Byte buffer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_String_insertFrontByteBuffer

void
Arcadia_String_insertFrontByteBuffer
  (
    Arcadia_Thread* thread,
    Arcadia_String* self,
    Arcadia_ByteArrayBuilder* target
  ) Insert the Bytes of this string into the Byte buffer at the front.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.
Arcadia_ByteArrayBuilder* target
A pointer to the Byte buffer.

Errors

Arcadia_Status_ArgumentValueInvalid
self or target is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_String_insertBackByteBuffer

void
Arcadia_String_insertBackByteBuffer
  (
    Arcadia_Thread* thread,
    Arcadia_String* self,
    Arcadia_ByteArrayBuilder* target
  ) Insert the Bytes of this string into the Byte buffer at the back.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.
Arcadia_ByteArrayBuilder* target
A pointer to the Byte buffer.

Errors

Arcadia_Status_ArgumentValueInvalid
self or target is a null pointer.
Arcadia_Status_AllocationFailed
An allocation failed.

Time

This section documents the time API of Arcadia Ring 2. A point in time is represented by a timestamp - an Arcadia_Integer64Value - and by an Arcadia_PointInTime object which provides access to the date and time fields of the represented moment. The date and time fields can be interpreted in either universal time coordinated (UTC) or local time, as determined by an Arcadia_TimeSpecification value.

Arcadia_TimeSpecification

typedef implementation detail Arcadia_TimeSpecification The Arcadia_TimeSpecification type is an enumeration type determining the time specification in which the date and time fields of a point in time are represented.

Arcadia_TimeSpecification_Utc

#define Arcadia_TimeSpecification_Utc implementation detail The Arcadia_TimeSpecification_Utc value denotes time in the Universal Time Coordinated (UTC) time specification.

Arcadia_TimeSpecification_LocalTime

#define Arcadia_TimeSpecification_LocalTime implementation detail The Arcadia_TimeSpecification_LocalTime value denotes time in the local time specification.

Arcadia_PointInTime

Arcadia_PointInTime extends Arcadia_Object.

Arcadia_PointInTime represents a point in time. The point in time is given by a timestamp, the number of seconds since the start of the epoch.

Arcadia_TimeStamp_getNow

Arcadia_Integer64Value
Arcadia_TimeStamp_getNow
  (
    Arcadia_Thread* thread
  ) Get the timestamp of now. The timestamp is the number of seconds since the start of the epoch and is independent of any time specification.

Parameters

A pointer to the Arcadia_Thread object.

Return value

The timestamp of now.

Arcadia_PointInTime_create

Arcadia_PointInTime*
Arcadia_PointInTime_create
  (
    Arcadia_Thread* thread,
    Arcadia_Integer64Value timeStamp
  ) Create a point in time from a timestamp.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_Integer64Value timeStamp
The timestamp. A timestamp is the number of seconds since the start of the epoch.

Return value

A pointer to the Arcadia_PointInTime object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_PointInTime_getDayOfWeek

Arcadia_Integer8Value
Arcadia_PointInTime_getDayOfWeek
  (
    Arcadia_Thread* thread,
    Arcadia_PointInTime* self,
    Arcadia_TimeSpecification timeSpecification
  ) Get the day of the week of this point in time.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_PointInTime* self
A pointer to this point in time.
Arcadia_TimeSpecification timeSpecification
The time specification in which the day of the week shall be represented.

Return value

The day of the week, in the range [0,6]. 0 denotes Sunday, 6 denotes Saturday.

Errors

Arcadia_Status_ArgumentValueInvalid
The value of timeSpecification is not a value of the Arcadia_TimeSpecification type.
Arcadia_Status_EnvironmentFailed
The environment failed to convert the timestamp.

Arcadia_PointInTime_getDayOfMonth

Arcadia_Integer8Value
Arcadia_PointInTime_getDayOfMonth
  (
    Arcadia_Thread* thread,
    Arcadia_PointInTime* self,
    Arcadia_TimeSpecification timeSpecification
  ) Get the day of the month of this point in time.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_PointInTime* self
A pointer to this point in time.
Arcadia_TimeSpecification timeSpecification
The time specification in which the day of the month shall be represented.

Return value

The day of the month, in the range [0,30]. The day is zero based, 0 denotes the first day of the month.

Errors

Arcadia_Status_ArgumentValueInvalid
The value of timeSpecification is not a value of the Arcadia_TimeSpecification type.
Arcadia_Status_EnvironmentFailed
The environment failed to convert the timestamp.

Arcadia_PointInTime_getMonth

Arcadia_Integer8Value
Arcadia_PointInTime_getMonth
  (
    Arcadia_Thread* thread,
    Arcadia_PointInTime* self,
    Arcadia_TimeSpecification timeSpecification
  ) Get the month of the year of this point in time.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_PointInTime* self
A pointer to this point in time.
Arcadia_TimeSpecification timeSpecification
The time specification in which the month of the year shall be represented.

Return value

The month of the year, in the range [0,11]. The month is zero based, 0 denotes January, 11 denotes December.

Errors

Arcadia_Status_ArgumentValueInvalid
The value of timeSpecification is not a value of the Arcadia_TimeSpecification type.
Arcadia_Status_EnvironmentFailed
The environment failed to convert the timestamp.

Arcadia_PointInTime_getYear

Arcadia_Integer32Value
Arcadia_PointInTime_getYear
  (
    Arcadia_Thread* thread,
    Arcadia_PointInTime* self,
    Arcadia_TimeSpecification timeSpecification
  ) Get the year of this point in time.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_PointInTime* self
A pointer to this point in time.
Arcadia_TimeSpecification timeSpecification
The time specification in which the year shall be represented.

Return value

The year. The returned value is the number of years since 1900; adding 1900 to the returned value yields the calendar year.

Errors

Arcadia_Status_ArgumentValueInvalid
The value of timeSpecification is not a value of the Arcadia_TimeSpecification type.
Arcadia_Status_EnvironmentFailed
The environment failed to convert the timestamp.