\[ \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 1

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

Files

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

Arcadia Ring 1 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 1 relies on Arcadia ARMS.

Foundational Types

Arcadia_BooleanValue

typedef implementation detail Arcadia_BooleanValue The C representation of the Arcadia.Boolean type.

Arcadia_BooleanValue_True

#define Arcadia_BooleanValue_True implementation detail The C representation of the value Arcadia.Boolean.True denoting logically true. It converts to 1 in arithmetic expressions.

Arcadia_BooleanValue_False

#define Arcadia_BooleanValue_False implementation detail The C representation of the value Arcadia.Boolean.False denoting logically false. It converts to 0 in arithmetic expressions.

Arcadia_ForeignProcedureValue

typedef implementation detail Arcadia_ForeignProcedureValue; A pointer to a function adhering to the calling conventions for C functions.

Arcadia_ForeignProcedureValue_Null

#define Arcadia_ForeignProcedureValue_Null implementation detail The Arcadia_ForeignProcedureValue value indicating the absence of a function. This usually evaluates to ((void*)0).

Arcadia_ForeignProcedureValue_NumberOfBits

#define Arcadia_ForeignProcedureValue_NumberOfBits implementation detail The number of Bits an Arcadia_ForeignProcedureValue occupies. This is a value is a positive multiple of 8.

Arcadia_ForeignProcedureValue_NumberOfBytes

#define Arcadia_ForeignProcedureValue_NumberOfBytes implementation detail The number of Bytes of the type which is usually Arcadia_ForeignProcedureValue_NumberOfBits divided by 8.

Arcadia_Integer*Value

typedef implementation detail Arcadia_IntegerSuffixValue Two's complment integer number types where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

Arcadia_Integer*Value_NumberOfBits

#define Arcadia_IntegerSuffixValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_IntegerSuffix occupies where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64. The value is always equal to the value of the respective Suffix.

Arcadia_Integer*Value_NumberOfBytes

#define Arcadia_IntegerSuffixValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_IntegerSuffixValue occupies where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64. The value is always equal to Arcadia_IntegerSuffixValue_NumberOfBits divided by 8.

Arcadia_Integer*Value_Maximum

#define Arcadia_IntegerSuffixValue_Maximum implementation detail The greatest value representable by a the Arcadia_IntegerSuffixValue type where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 127
16 32767
32 2147483647
64 9223372036854775807

Arcadia_Integer*Value_Minimum

#define Arcadia_IntegerSuffixValue_Minimum implementation detail The least value representable by a the Arcadia_IntegerSuffixValue type where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 -128
16 -32768
32 -2147483648
64 -9223372036854775808

Arcadia_Integer*Value_Literal

#define Arcadia_IntegerSuffixValue_Literal(x) implementation detail Macro used to write a literal of the type Arcadia_IntegerSuffixValue in C source code where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The following table denotes the expansions of the macro:

SuffixValue
8 x
16 x
32 x
64 x##LL

Arcadia_Natural*Value

typedef implementation detail Arcadia_NaturalSuffixValue Unsigned integer number type where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64.

Arcadia_Natural*Value_NumberOfBits

#define Arcadia_NaturalSuffixValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_NaturalSuffix occupies where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64. The value is always equal to the value of the respective Suffix.

Arcadia_Natural*Value_NumberOfBytes

#define Arcadia_IntegerSuffixValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_NaturalSuffixValue occupies where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64. The value is always equal to Arcadia_NaturalSuffixValue_NumberOfBits divided by 8.

Arcadia_Natural*Value_Minimum

#define Arcadia_NaturalSuffixValue_Minimum implementation detail The least value representable by a the Arcadia_NaturalSuffixValue type where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64. Suffix

SuffixValue
8 0
16 0
32 0
64 0

Arcadia_Natural*Value_Maximum

#define Arcadia_NaturalSuffixValue_Maximum implementation detail The greatest value representable by a the Arcadia_NaturalSuffixValue type where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64.

The following table denotes the value of the constant for the respective Suffix

ConstantValue
8 255
16 65535
32 4294967295
64 18446744073709551615

Arcadia_Natural*Value_Literal

#define Arcadia_NatualSuffixValue_Literal(x) implementation detail Macro used to write a literal of the type Arcadia_NaturalSuffixValue in C source code where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64.

The following table denotes the expansions of the macro:

SuffixValue
8 x
16 x
32 x##U
64 x##ULL

Arcadia_ObjectReferenceValue

typedef implementation detail Arcadia_ObjectReferenceValue The Arcadia_ObjectReferenceValue type is a pointer which assume the value Arcadia_ObjectReferenceValue_Null or point to a Arcadia_Object or derived type value.

Arcadia_ObjectReferenceValue_Null

#define Arcadia_ObjectReferenceValue_Null implementation detail The Arcadia_ObjectReferenceValue_Null value indicating the absence of a an Arcadia_Object or derived type value. This usually evaluates to ((void*)0).

Arcadia_ObjectReferenceValue_NumberOfBits

#define Arcadia_ObjectReferenceValue_NumberOfBits implementation detail Denotes the number of Bits of the type.

Arcadia_ObjectReferenceValue_NumberOfBytes

#define Arcadia_ObjectReferenceValue_NumberOfBytes implementation detail Denotes the number of Bytes of the type which is usually Arcadia_ObjectReferenceValue_NumberOfBits divided by 8.

Arcadia_Real*Value

typedef implementation detail Arcadia_RealSuffixValue IEEE 754 binary real number type where Suffix denotes the number of Bits of the type and can be one of 32 or 64.

Arcadia_Real*Value_NumberOfBits

The macros in this section all include the Suffix metavariable and are defined for the values 32 and 64.

#define Arcadia_RealSuffixValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_VoidValue occupies where Suffix denotes the number of Bits of the type and can be one of 32 or 64. This is a positive multiple of 8.

Arcadia_Real*Value_NumberOfBytes

#define Arcadia_RealSuffixValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_RealSuffixValue occupies where Suffix denotes the number of Bits of the type and can be one of 32 or 64. The value is always equal to Arcadia_RealSuffixValue_NumberOfBits divided by 8.

Arcadia_Real*Value_Maximum

#define Arcadia_RealSuffixValue_Maximum implementation detail The greatest value representable by a the Arcadia_RealSuffixValue type.

The following table denotes the value of the constant for the respective Suffix

ConstantValue
32 +FLT_MAX
64 +DBL_MAX

Arcadia_Real*Value_Minimum

#define Arcadia_RealSuffixValue_Minimum implementation detail The least value representable by a the Arcadia_RealSuffixValue type where Suffix denotes the number of Bits of the type and can be one of 32 or 64. summary>

The following table denotes the value of the constant for the respective Suffix

SuffixValue
32 -FLT_MAX
64 -DBL_MAX

Size Type

typedef implementation detail Arcadia_SizeValue An alias for the builtin size_t type.

Arcadia_SizeValue_NumberOfBits

#define Arcadia_SizeValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_SizeValue occupies. This is a positive multiple of 8. This number must one of 32 or 64, otherwise the environment is not supported by Arcadia Ring 1. This restriction may be relaxed in future versions of Arcadia Ring 1.

Arcadia_SizeValue_NumberOfBytes

#define Arcadia_SizeValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_SizeValue occupies. The value is always equal to Arcadia_SizeValue divided by 8.

Arcadia_SizeValue_Maximum

#define Arcadia_SizeValue_Maximum implementation detail The greatest value representable by a the Arcadia_SizeValue type.

Arcadia_SizeValue_Minimum

#define Arcadia_SizeValue_Minimum implementation detail The least value representable by a the Arcadia_SizeValue type.

Arcadia_SizeValue_Literal

#define Arcadia_SizeValue_Literal(x) implementation detail Macro used to write a literal of the type Arcadia_SizeValue in C source code.

Arcadia_VoidValue

typedef implementation detail Arcadia_VoidValue The only value of this type is Arcadia_VoidValue_Void. Arcadia_VoidValue is an unsigned integral type.

Arcadia_VoidValue_Void

#define Arcadia_VoidValue_Void implementation detail The single value of the type Arcadia_VoidValue.

Arcadia_VoidValue_NumberOfBits

#define Arcadia_VoidValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_VoidValue occupies. This is a positive multiple of 8.

Arcadia_VoidValue_NumberOfBytes

#define Arcadia_VoidValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_VoidValue occupies. The value is always equal to Arcadia_VoidValue divided by 8.

Union Types

Arcadia_Value

typedef struct { implementation detail } Arcadia_Value Arcadia_Value is a tagged union of values supported by the runtime. It consists of a tag indicating the value stored in the union and the union of the values. The following table lists all possible tags and their corresponding type.
Tag Type
Arcadia_ValueTag_Atom Arcadia_AtomValue
Arcadia_ValueTag_Boolean Arcadia_BooleanValue
Arcadia_ValueTag_Integer16 Arcadia_Integer16Value
Arcadia_ValueTag_Integer32 Arcadia_Integer32Value
Arcadia_ValueTag_Integer64 Arcadia_Integer64Value
Arcadia_ValueTag_Integer8 Arcadia_Integer8Value
Arcadia_ValueTag_Natural16 Arcadia_Natural16Value
Arcadia_ValueTag_Natural32 Arcadia_Natural32Value
Arcadia_ValueTag_Natural64 Arcadia_Natural64Value
Arcadia_ValueTag_Natural8 Arcadia_Natural8Value
Arcadia_ValueTag_ObjectReferenceArcadia_ObjectReferenceValue
Arcadia_ValueTag_Real32 Arcadia_Real32Value
Arcadia_ValueTag_Real64 Arcadia_Real64Value
Arcadia_ValueTag_Size Arcadia_SizeValue
Arcadia_ValueTag_Type Arcadia_TypeValue
Arcadia_ValueTag_Void Arcadia_VoidValue

For each type, Arcadia_Value has three functions associated:

Type Arcadia_Value_getSuffix(Arcadia_Value const* value)
bool Arcadia_Value_isSuffix(Arcadia_Value const* value)
void Arcadia_Value_setSuffix(Arcadia_Value* value, Arcadia_SuffixValue VariableValue)

The following table lists the valid combinations of Suffix and Variable

Atom atom
Boolean boolean
Integer16 integer16
Integer32 integer32
Integer64 integer64
Integer8 integer8
Natural16 natural16
Natural32 natural32
Natural64 natural64
Natural8 natural8
Real32 reall32
Real64 real64
ObjectReferenceobjectReference
Size size
Type type
Void void

Arcadia_Value_isSuffix returns true if the Arcadia_Value stores a value of the type corresponding to Suffix. Otherwise it returns false.

Arcadia_Value_setSuffix assigns the Arcadia_Value a value of the type corresponding to Suffix.

Arcadia_Value_getType get the value stored in the Arcadia_Value. The behavior of Arcadia_Value_setSuffix is undefined if the value does not store a value of the type corresponding to Suffix.

Arcadia_Value_hash

Arcadia_Size
Arcadia_Value_hash
  (
    Arcadia_Thread* thread,
    Arcadia_Value* self
  ); Get the hash value of this Arcadia_Value.

Parameters

thread
A pointer to the Arcadia_Thread object.
self
A pointer to this Arcadia_Value object.

Return value

The hash of the value of the value of thisArcadia_Value object.

Arcadia_Value_isEqualTo

Arcadia_BooleanValue
Arcadia_Value_isEqualTo
  (
    Arcadia_Thread* thread,
    Arcadia_Value* self,
    Arcadia_Value* other
  ); Compare the value of this Arcadia_Value object to the value of another Arcadia_Value object.

Parameters

thread
A pointer to the Arcadia_Thread object.
self
A pointer to this Arcadia_Value object.
other
A pointer to the other Arcadia_Value object.

Return value

Arcadia_BooleanValue_True if the value of this Arcadia_Value object is equal to the value of the other Arcadia_Value object. Arcadia_BooleanValue_False otherwise.

Status codes and status variables

Status Codes

R provides a status type and symbolic constants for its values. That type denotes success or failure of program (or a part of it) as well as information on the reason for the failure.

typedef implementation detail Arcadia_Status

Arcadia_Status is a natural number type of a width of 32 Bit.

#definer Arcadia_Status_Success implementation detail

is the symbolic constant of the type Arcadia_Status has the value ((Arcadia_Status)0). It denotes success and is guaranteed to be defined to the value 0 of the underlaying natural number type of Arcadia_Status as well as to be the only symbolic constant starting with Arcadia_Status_ having defined to that value.

Symbolic constants of the form

#definer Arcadia_Status_Name implementation detail

where Name is not Success provide information on failure of a program (or a part of it). The following table denotes the value of the constant for the respective Name

Name Value
AccessDenied An access was denied.
AllocationFailed An allocation failed.
ArgumentTypeInvalid The type of an argument is invalid.
ArgumentValueInvalid The value of an argument is invalid.
ConversionFailed A conversion failed.
DivisionByZero An divions by zero was detected.
EncodingInvalid An encoding is invalid.
EnvironmentFailed The environment failed.
Exists Something exists (but should not).
Found Something was found.
Initialized Something was initialized (but should not have been initialized).
LexicalError A lexical error.
NotExists Something does not exist.
NotFound Something was not found.
NumberOfArgumentsInvalid The number of arguments is invalid.
OperationFailed An operation failed.
OperationInvalid An operation is invalid.
SemanticalError A semantical error.
SyntacticalError A syntactical error.
TestFailed A test failed. This is used by the built-in tests that ensure correctness.
TypeExists A type exists (but should not).
TypeNotExists A type does not exist (but should).
Uninitialized Something was uninitialized (but should have been initialized).

Status Variable

Arcadia.Ring1 provides by-thread status variable.

Arcadia_Status Arcadia_Thread_getStatus ( Arcadia_Thread* thread );

gets the value of the status variable. The initial value of the status variable is Arcadia_Status_Success.

void Arcadia_Thread_setStatus ( Arcadia_Thread* thread, Arcadia_Status status );

sets the value of the status variable to the value status.

Jumps and jump targets

Jumps and Jump Targets

Arcadia.Ring1 provides non-local jumps by allowing to save and restore the C program state.

typedef implementation detail Arcadia_JumpTarget;

is a type of which its values are stack allocated.

void Arcadia_Thread_pushJumpTarget(Arcadia_Thread* thread, Arcadia_JumpTarget* jumpTarget);

Push a jump target on top of the jump target stack. Initially, the jump target stack is empty.

void Arcadia_Thread_popJumpTarget(Arcadia_Thread* thread);

Pop the jump target on top of the jump target stack. The jump target stack must not be empty.

void Arcadia_jump(Arcadia_Thread* thread);

Jump to the jump target on top of the jump target stack. The jump target stack must not be empty.

#define Arcadia_JumpTarget_save(jumpTarget) implementation detail

Macro to save the current C program state into a jump target.

The canonical way of using Arcadia_Thread_pushJumpTarget, Arcadia_Thread_popJumpTarget, and Arcadia_Thread_jump is the following.

Arcadia_Thread_pushJumpTarget(thread, &jumpTarget);
if (Arcadia_JumpTarget_save(thread, &jumpTarget)) {
 (1)
 Arcadia_Thread_popJumpTarget(thread);(2)
} else {
 Arcadia_Thread_popJumpTarget(thread);(3)
 (4)
}
(5)

The if-branch is always entered at first as the Arcadia_JumpTarget_save() at its first invocation returns logically true. If the program at (1) does not jump to the jump target (using Arcadia_Thread_jump()), then Arcadia_Thread_popJumpTarget(); (2) and (5) are executed. If the program at (1) jumps to the jump target, then Arcadia_Thread_JumpTarget_save() is re-evaluated and returns logically false and Arcadia_Thread_popJumpTarget();(2) and (4) is executed.

One usage example is the implementation of the Arcadia_safeExecute function.

void Arcadia_safeExecute(Arcadia_Thread* thread, void (*f)(Arcadia_Thread*)) {
 Arcadia_JumpTarget jumpTarget;
 Arcadia_Thread_pushJumpTarget(thread, &jumpTarget);
 if (Arcadia_Thread_JumpTarget_save(thread, &jumpTarget)) {
  f();
  Arcadia_Thread_popJumpTarget(thread);
 }
}

Objects

Arcadia_Object

Arcadia_Object is the ancestor type from which so called object types derive from.

Arcadia_Object types are allocated on the heap and can are referenced by Arcadia_Object* pointers.

Object Lifetime and Method Invocation

An ordinary method may be invoked on an Arcadia_Object or derived object only if the object is fully constructed and has not entered finalization.

At the point of invocation, the receiver must be a GC root or transitively reachable from a GC root. It must remain reachable throughout the invocation, including during garbage collections triggered by nested calls. A C pointer, including self, does not by itself constitute a GC root.

The caller is responsible for satisfying these preconditions. An ordinary method is not required to root its receiver automatically. Temporary roots can be established through the Arcadia value stack or Arcadia_Object_lock; an owning object can retain references through its visit callback.

Constructors and finalizers are lifecycle operations rather than ordinary method invocations. A finalizer must not assume that another unreachable managed object remains valid: the garbage collector does not guarantee finalization order.

Arcadia_Object_getHash

Arcadia_SizeValue
Arcadia_Object_getHash
  (
    Arcadia_Thread* thread,
    Arcadia_Object* self
  ) Get the hash of this Arcadia_Object or derived type value.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_Object* self
A pointer to this code>Arcadia_Object or derived type value.

Return value

The hash of this code>Arcadia_Object or derived type value.

Arcadia_Object_isEqualTo

Arcadia_BooleanValue
Arcadia_Object_isEqualTo_pn
  (
    Arcadia_Thread* thread,
    Arcadia_Object* self,
    Arcadia_Value other
  ) Get if this Arcadia_Object or derived type value is equal to the specified value other.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_Object* self
A pointer to this code>Arcadia_Object or derived type value.
Arcadia_Value other
The other value.

Return value

Arcadia_BooleanValue_True if this code>Arcadia_Object or derived type value is equal to the other value. Arcadia_BooleanValue_False otherwise.

Arcadia_Object_isNotEqualTo

Arcadia_BooleanValue
Arcadia_Object_isEqualTo_pn
  (
    Arcadia_Thread* thread,
    Arcadia_Object* self,
    Arcadia_Value other
  ) Get if this Arcadia_Object or derived type value is not equal to the specified value other.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_Object* self
A pointer to this code>Arcadia_Object or derived type value.
Arcadia_Value other
The other value.

Return value

Arcadia_BooleanValue_True if this code>Arcadia_Object or derived type value is not equal to the other value. Arcadia_BooleanValue_False otherwise.

Arcadia_ByteArray

Arcadia_ByteArray extends Arcadia_Object.

Arcadia_ByteArray represents a mutable sequence of Bytes.

Arcadia_ByteArray_getAt

Arcadia_Natural8Value
Arcadia_ByteArray_getAt
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArray const* self,
    Arcadia_SizeValue index
  ) Get the Byte value at the specified index. Remarks: The size of a Byte array is the length of the Byte sequence it contains.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArray* self
A pointer to this Byte array.
Arcadia_SizeValue index
The index. Must be within the bounds [0,n) where n is the size of this Byte array.

Return value

The Byte value.

Arcadia_ByteArray_getBytes

void const*
Arcadia_ByteArray_getBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArray const* self
  ) Get a pointer to the Bytes in this Byte array. Warning: The Bytes must not be modified. The pointer is valid only as long as the Byte array object is valid and is not modified.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArray* self
A pointer to this Byte array.

Return value

A pointer to the Bytes in this Byte array.

Arcadia_ByteArray_getNumberOfBytes

Arcadia_SizeValue
Arcadia_ByteArray_getNumberOfBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArray const* self
  ) Get the number of Bytes in this Byte array. Remarks: This is an alias of Arcadia_ByteArray_getSize.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArray* self
A pointer to this Byte array.

Return value

The size of this Byte array.

Arcadia_ByteArray_getSize

Arcadia_SizeValue
Arcadia_ByteArray_getSize
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArray const* self
  ) Get the size of this Byte array. Remarks: The size of a Byte array is the number of Bytes in that Byte array. This is an alias of Arcadia_ByteArray_getNumberOfBytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArray* self
A pointer to this Byte array.

Return value

The size of this Byte array.

Arcadia_ByteArray_isEmpty

Arcadia_BooleanValue
Arcadia_ByteArray_isEmpty
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArray* self
  ) Get if this Byte array is empty.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArray* self
A pointer to this Byte array.

Return value

Arcadia_BooleanValue_True if this Byte array is empty. Arcadia_BooleanValue_False otherwise.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_ByteArrayBuilder

Arcadia_ByteArrayBuilder extends Arcadia_Object.

Arcadia_ByteArrayBuilder represents a mutable sequence of Bytes.

Arcadia_ByteArrayBuilder_clear

void
Arcadia_ByteArrayBuilder_clear
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self
  ) Set the number of elements of this Byte buffer to zero.

Parameters

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

Arcadia_ByteArrayBuilder_create

Arcadia_ByteArrayBuilder*
Arcadia_ByteArrayBuilder_create
  (
    Arcadia_Thread* thread
  ) Create a Byte buffer.

Parameters

A pointer to the Arcadia_Thread object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to the Arcadia_ByteArrayBuilder object.

Arcadia_ByteArrayBuilder_getBytes

void const*
Arcadia_ByteArrayBuilder_getBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder const* self
  ) Get a pointer to the Bytes in this Byte buffer. Warning: The Bytes must not be modified. The pointer is valid only as long as the Byte buffer object is valid and is not modified.

Parameters

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

Return value

A pointer to the Bytes in this Byte buffer.

Arcadia_ByteArrayBuilder_getNumberOfBytes

Arcadia_SizeValue
Arcadia_ByteArrayBuilder_getNumberOfBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder const* self
  ) Get the number of Bytes in this Byte buffer. Remarks: This is an alias of Arcadia_ByteArrayBuilder_getSize.

Parameters

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

Return value

The size of this Byte buffer.

Arcadia_ByteArrayBuilder_getSize

Arcadia_SizeValue
Arcadia_ByteArrayBuilder_getSize
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder const* self
  ) Get the size of this Byte buffer. Remarks: The size of a Byte buffer is the number of Bytes in that Byte buffer. This is an alias of Arcadia_ByteArrayBuilder_getNumberOfBytes.

Parameters

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

Return value

The size of this Byte buffer.

Arcadia_ByteArrayBuilder_insertBackBytes

void
Arcadia_ByteArrayBuilder_insertBackBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Append Bytes to this Byte buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Errors

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

Arcadia_ByteArrayBuilder_insertBytes

void
Arcadia_ByteArrayBuilder_insertBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self,
    Arcadia_SizeValue index,
    void const* p,
    Arcadia_SizeValue n
  ) Insert Bytes into this Byte buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
Arcadia_SizeValue index
The index at which to insert the Bytes. Must be within the bounds of [0,n) where n is the size of this Byte buffer.
void const* p
A pointer to an array of n Bytes.
Arcadia_SizeValue n
The number of Bytes in the array pointed to by p.

Errors

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

Arcadia_ByteArrayBuilder_insertFrontBytes

void
Arcadia_ByteArrayBuilder_insertFrontBytes
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self,
    void const* p,
    Arcadia_SizeValue n
  ) Prepend Bytes to this Byte buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
void const* p
A pointer to an array of n Bytes.
Arcadia_SizeValue n
The number of Bytes in the array pointed to by p.

Errors

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

Arcadia_ByteArrayBuilder_endsWith_pn

Arcadia_BooleanValue
Arcadia_ByteArrayBuilder_endsWith_pn
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder const* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Get if a sequence of Bytes is a suffix of this Byte buffer's sequence of Bytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Return value

Arcadia_BooleanValue_True if the sequence of Bytes is a suffix of this byte buffer's sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_ByteArrayBuilder_startsWith_pn

Arcadia_BooleanValue
Arcadia_ByteArrayBuilder_startsWith_pn
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Get if a sequence of Bytes is a prefix of this Byte buffer's sequence of Bytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Return value

Arcadia_BooleanValue_True if the sequence of Bytes is a prefix of this byte buffer's sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_isEqualTo_pn

Arcadia_BooleanValue
Arcadia_ByteArrayBuilder_isEqualTo_pn
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Get if a sequence of Bytes is this Byte buffer's sequence of Bytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Return value

Arcadia_BooleanValue_True if the sequence of Bytes is this byte buffer's sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_ByteArrayBuilder_isEqualTo

Arcadia_BooleanValue
Arcadia_ByteArrayBuilder_isEqualTo
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder const* self,
    Arcadia_ByteArrayBuilder const* other
  ) Compare this Byte buffer with another Byte buffer for equality.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder const* self
A pointer to this Byte buffer.
Arcadia_ByteArrayBuilder const* other
A pointer to the other Byte buffer.

Return value

Arcadia_BooleanValue_True if this Byte buffer is equal to the other Byte buffer. Arcadia_BooleanValue_False otherwise.

Arcadia_ByteArrayBuilder_getAt

Arcadia_Natural8Value
Arcadia_ByteArrayBuilder_getAt
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder const* self,
    Arcadia_SizeValue index
  ) Get the Byte value at the specified index. Remarks: The size of a Byte buffer is the length of the Byte sequence it contains.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
Arcadia_SizeValue index
The index. Must be within the bounds [0,n) where n is the size of this Byte buffer.

Return value

The Byte value.

Arcadia_ByteArrayBuilder_isEmpty

Arcadia_BooleanValue
Arcadia_ByteArrayBuilder_isEmpty
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self
  ) Get if this Byte buffer is empty.

Parameters

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

Return value

Arcadia_BooleanValue_True if this Byte buffer is empty. Arcadia_BooleanValue_False otherwise.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_ByteArrayBuilder_swap

void
Arcadia_ByteArrayBuilder_swap
  (
    Arcadia_Thread* thread,
    Arcadia_ByteArrayBuilder* self,
    Arcadia_ByteArrayBuilder* other
  ) Swap the contents of this Byte buffer with the contents of another Byte buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_ByteArrayBuilder* self
A pointer to this Byte buffer.
Arcadia_ByteArrayBuilder* self
A pointer to the other Byte buffer.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
other is a null pointer.

Arcadia_String

Arcadia_String extends Arcadia_Object.

Arcadia_String represents an immutable sequence of Unicode code points in UTF8 encoding.

Arcadia_String derives fro Arcadia_Object and overrides the following methods:

  • Arcadia_Object_isEqualTo
  • Arcadia_Object_isNotEqualTo
  • Arcadia_Object_getHash

Arcadia_String_createFromBoolean

Arcadia_String*
Arcadia_String_createFromBoolean
  (
    Arcadia_Thread* thread,
    Arcadia_BooleanValue booleanValue
  ) Create a string from an Arcadia_BooleanValue value. The Arcadia_BooleanValue value is converted to the strings true, if its value is Arcadia_BooleanValue_True, and false, if its value is Arcadia_BooleanValue_False, respectively.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_BooleanValue booleanValueThe Arcadia_BooleanValue to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromInteger16

Arcadia_String*
Arcadia_String_createFromInteger16
  (
    Arcadia_Thread* thread,
    Arcadia_Integer16Value integer16Value
  ) Create a string from an Arcadia_Integer16Value value. The Arcadia_Integer16Value value is converted to the decimal integer number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Integer16Value integer16ValueThe Arcadia_Integer16Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromInteger32

Arcadia_String*
Arcadia_String_createFromInteger32
  (
    Arcadia_Thread* thread,
    Arcadia_Integer32Value integer32Value
  ) Create a string from an Arcadia_Integer32Value value. The Arcadia_Integer32Value value is converted to the decimal integer number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Integer32Value integer32ValueThe Arcadia_Integer32Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromInteger64

Arcadia_String*
Arcadia_String_createFromInteger64
  (
    Arcadia_Thread* thread,
    Arcadia_Integer64Value integer64Value
  ) Create a string from an Arcadia_Integer64Value value. The Arcadia_Integer64Value value is converted to the decimal integer number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Integer64Value integer64ValueThe Arcadia_Integer64Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromInteger8

Arcadia_String*
Arcadia_String_createFromInteger8
  (
    Arcadia_Thread* thread,
    Arcadia_Integer8Value integer8Value
  ) Create a string from an Arcadia_Integer8Value value. The Arcadia_Integer8Value value is converted to the decimal integer number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Integer8Value integer8ValueThe Arcadia_Integer8Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromNatural16

Arcadia_String*
Arcadia_String_createFromNatural16
  (
    Arcadia_Thread* thread,
    Arcadia_Natural16Value natural64Value
  ) Create a string from an Arcadia_Natural16Value value. The Arcadia_Natural16Value value is converted to the decimal natural number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Natural16Value natural16ValueThe Arcadia_Natural16Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromNatural32

Arcadia_String*
Arcadia_String_createFromNatural32
  (
    Arcadia_Thread* thread,
    Arcadia_Natural32Value natural64Value
  ) Create a string from an Arcadia_Natural32Value value. The Arcadia_Natural32Value value is converted to the decimal natural number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Natural32Value natural32ValueThe Arcadia_Natural32Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromNatural64

Arcadia_String*
Arcadia_String_createFromNatural64
  (
    Arcadia_Thread* thread,
    Arcadia_Natural64Value natural64Value
  ) Create a string from an Arcadia_Natural64Value value. The Arcadia_Natural64Value value is converted to the decimal natural number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Natural64Value natural64ValueThe Arcadia_Natural64Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromNatural8

Arcadia_String*
Arcadia_String_createFromNatural8
  (
    Arcadia_Thread* thread,
    Arcadia_Natural8Value natural64Value
  ) Create a string from an Arcadia_Natural8Value value. The Arcadia_Natural8Value value is converted to the decimal natural number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Natural8Value natural8ValueThe Arcadia_Natural8Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromReal32

Arcadia_String*
Arcadia_String_createFromReal32
  (
    Arcadia_Thread* thread,
    Arcadia_Real32Value real32Value
  ) Create a string from an Arcadia_Real3lValue value. The Arcadia_Real32Value value is converted to the decimal real number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Real32Value real32ValueThe Arcadia_Real32Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromReal64

Arcadia_String*
Arcadia_String_createFromReal64
  (
    Arcadia_Thread* thread,
    Arcadia_Real64Value real64Value
  ) Create a string from an Arcadia_Real64Value value. The Arcadia_Real64Value value is converted to the decimal real number literal string.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_Real64Value real64ValueThe Arcadia_Real64Value to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_createFromVoid

Arcadia_String*
Arcadia_String_createFromBoolean
  (
    Arcadia_Thread* thread,
    Arcadia_VoidValue voidValue
  ) Create a string from an Arcadia_VoidValue value. The Arcadia_VoidValue value is converted to the string void.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_VoidValue voidValueThe Arcadia_VoidValue to be converted into the string value.

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_String_create_pn

Arcadia_String*
Arcadia_String_create_pn
  (
    Arcadia_Thread* thread,
    Arcadia_ImmutableByteArray* immutableByteArray
  ) Create a string from an immutable Byte array.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_ImmutableByteBuffer* immutableByteArrayA pointer to the Arcadia_ImmutableByteArray object

Return value

A pointer to the Arcadia_String object.

Errors

Arcadia_Status_ArgumentValueInvalidimmutableByteArray is a null pointer. Arcadia_Status_EncodingInvalid The sequence of Bytes does not represented a UTF-8-NO-BOM string.

Arcadia_String_create

Arcadia_String*
Arcadia_String_create
  (
    Arcadia_Thread* thread,
    Arcadia_Value value
  )

Create a string from a value.

The following values are accepted:

The specified value may contain a Arcadia_ByteBuffer object. In that case, the string is created from the Bytes of the Byte buffer object. A Arcadia_Status_EncodingInvalid is raised if the Byte sequence of that Arcada_ByteBuffer object is not a UTF8 Byte sequence.

The specified value may contain a Arcadia_ImmutableByteArray object. In that case, the string is created from the Arcadia_ImmutableByteArray object. A Arcadia_Status_EncodingInvalid is raised if the Byte sequence of that Arcada_ImmutableByteArray object is not a UTF8 Byte sequence.

The specified value may contain a Arcadia_String object. In that case, the string is created from the Arcadia_String object.

The specified value may contain a Arcadia_StringBuffer object. In that case, the string is created from the Arcadia_StringBuffer object.

The specified value may contain a Arcadia_ImmutableUtf8String object. In that case, the string is created from the Arcadia_ImmutableUtf8String object.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Value value
The value.

Return value

A pointer to the string.

Errors

Arcadia_Status_ArgumentTypeInvalid
The value is not of type Arcadia_ByteBuffer, Arcadia_String, Arcadia_StringBuffer, or Arcadia_ImmutableByteArray.
Arcadia_Status_EncodingInvalid
The value is a Arcadia_ByteBuffer or Arcadia_ImmutableByteArray. However, the Byte sequence of that Arcadia_ByteBuffer or Arcadia_ImmutableByteArray object is not a UTF8 Byte sequence.

Arcadia_String_endsWith_pn

Arcadia_BooleanValue
Arcadia_String_endsWith_pn
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Get if a sequence of Bytes is a suffix of this string's sequence of Bytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Return value

Arcadia_BooleanValue_True if the sequence of Bytes is a suffix of this string's sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_String_startsWith_pn

Arcadia_BooleanValue
Arcadia_String_startsWith_pn
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Get if a sequence of Bytes is a prefix of this string's sequence of Bytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Return value

Arcadia_BooleanValue_True if the sequence of Bytes is a prefix of this string's sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_String_isEqualTo_pn

Arcadia_BooleanValue
Arcadia_String_isEqualTo_pn
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Get if a sequence of Bytes is this string's sequence of Bytes.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_String* self
A pointer to this string.
void const* bytes
A pointer to an array of n Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array pointed to by p.

Return value

Arcadia_BooleanValue_True if the sequence of Bytes is this string's sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_String_getNumberOfBytes

Arcadia_SizeValue
Arcadia_String_getNumberOfBytes
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Get the size, in Bytes, of this string.

Parameters

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

Return value

The size, in Bytes, of this string.

Arcadia_String_getBytes

Arcadia_Natural8Value const*
Arcadia_String_getBytes
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Get the Bytes of this string.

Parameters

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

Return value

A pointer to the Bytes of this string.

Arcadia_String_getByteAt

Arcadia_Natural8Value
Arcadia_String_getByteAt
  (
    Arcadia_String const* self,
    Arcadia_SizeValue index
  ) Get the Byte value 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. Must be within the bounds [0,n) where n is the size, in Bytes, of this string.

Return value

The Byte value.

Arcadia_String_toBoolean

Arcadia_BooleanValue
Arcadia_String_toBoolean
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as boolean literal and convert the boolean represented by that literal into an Arcadia_BooleanValue.

Parameters

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

Return value

The boolean value.

Errors

Arcadia_Status_ArgumentTypeInvalid self is a null pointer. Arcadia_Status_ConversionFailed The symbols of this string cannot be interpreted as a boolean literal. Valid boolean literals are true and false, both case sensitve.

Arcadia_String_toInteger16

Arcadia_Integer16Value
Arcadia_String_toInteger16
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as decimal integer literal and convert the number represented by that integer literal into an Arcadia_Integer16Value.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_String* selfA pointer to this string.

Return value

The integer value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal integer literal or the number represented by the literal cannot be represented a value of type Arcadia_Integer16Value.

Arcadia_String_toInteger32

Arcadia_Integer32Value
Arcadia_String_toInteger32
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as decimal integer literal and convert the number represented by that literal into an Arcadia_Integer32Value.

Parameters

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

Return value

The integer value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal integer literal or the number represented by the literal cannot be represented a value of type Arcadia_Integer32Value.

Arcadia_String_toInteger64

Arcadia_Integer64Value
Arcadia_String_toInteger64
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as decimal integer literal and convert the number represented by that literal into an Arcadia_Integer64Value.

Parameters

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

Return value

The integer value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal integer literal or the number represented by the literal cannot be represented a value of type Arcadia_Integer64Value.

Arcadia_String_toInteger8

Arcadia_Integer8Value
Arcadia_String_toInteger8
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as decimal integer literal and convert the number represented by that literal into an Arcadia_Integer8Value.

Parameters

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

Return value

The integer value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal integer literal or the number represented by the integer literal cannot be represented a value of type Arcadia_Integer8Value.

Arcadia_String_toNatural16

Arcadia_Natural16Value
Arcadia_Stringg_toNatural16
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as decimal natural literal and convert the number represented by that literal into an Arcadia_Natural16Value.

Parameters

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

Return value

The natural value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal natural literal or the number represented by the literal cannot be represented a value of type Arcadia_Natural16Value.

Arcadia_String_toNatural32

Arcadia_Natural32Value
Arcadia_String_toNatural32
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as decimal natural literal and convert the number represented by that literal into an Arcadia_Natural32Value.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_String* selfA pointer to this string.

Return value

The natural value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal natural literal or the number represented by the literal cannot be represented a value of type Arcadia_Natural32Value.

Arcadia_String_toNatural64

Arcadia_Natural64Value
Arcadia_String_toNatural64
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as a decimal natural literal and convert the number represented by that literal into an Arcadia_Natural64Value.

Parameters

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

Return value

The natural value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal natural literal or the number represented by the literal cannot be represented a value of type Arcadia_Natural64Value.

Arcadia_String_toNatural8

Arcadia_Natural8Value
Arcadia_String_toNatural8
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as a decimal natural literal and convert the number represented by that literal into an Arcadia_Natural8Value.

Parameters

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

Return value

The natural value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal natural literal or the number represented by the literal cannot be represented a value of type Arcadia_Natural8Value.

Arcadia_String_toReal32

Arcadia_Real32Value
Arcadia_String_toReal32
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as a decimal real literal and convert the number represented by that literal into an Arcadia_Real32Value.

Parameters

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

Return value

The Arcadia_Real32Value value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal real literal or the number represented by the literal cannot be represented a value of type Arcadia_Real32Value.

Arcadia_String_toReal64

Arcadia_Real64Value
Arcadia_String_toReal64
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as a decimal real literal and convert the number represented by that literal into an Arcadia_Real64Value.

Parameters

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

Return value

The Arcadia_Real64Value value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a decimal real literal or the number represented by the literal cannot be represented a value of type Arcadia_Real64Value.

Arcadia_String_toVoid

Arcadia_VoidValue
Arcadia_String_toVoid
  (
    Arcadia_Thread* thread,
    Arcadia_String const* self
  ) Interprete the symbols of this string as a void literal and convert the void value represented by that literal into an Arcadia_VoidValue.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_String* selfA pointer to this string.

Return value

The void value.

Errors

Arcadia_Status_ArgumentTypeInvalid
self is a null pointer.
Arcadia_Status_ConversionFailed
The symbols of this string cannot be interpreted as a void literal. The valid void literal is void, case sensitve.

Arcadia_StringBuilder

Arcadia_StringBuilder extends Arcadia_Object.

Arcadia_StringBuilder represents a mutable sequence of code points in UTF8 encoding.

Arcadia_StringBuilder_clear

void
Arcadia_StringBuilder_clear
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self
  ) Clear this string buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder self
A pointer to this string buffer.

Arcadia_StringBuilder_create

Arcadia_StringBuilder*
Arcadia_StringBuilder_create
  (
    Arcadia_Thread* thread
  ) Create a string buffer.

Parameters

A pointer to the Arcadia_Thread object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to the Arcadia_StringBuilder value.

Arcadia_StringBuilder_compareTo

Arcadia_Integer32Value*
Arcadia_StringBuilder_compareTo
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    Arcadia_Value other
  ) Compare the string in this string buffer with another string lexicographically.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder* self
A pointer to this string buffer.
Arcadia_Value other
The value to compare the UTF-8 string in this string buffer to. The value must be one of Arcadia.ImmutableUtf8String, Arcadia.StringBuilder, or Arcadia.String.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

  • A negative value is returned if the string in this string buffer is lexicographically less than the other string.
  • A positive value is returned if the string in this string buffer is lexicographically greater than the other string.
  • If both strings are lexicographically equal, then zero is returned.

Remarks

Let a and b be UTF-8 strings of n and m Bytes, respectively. Denote the i-th Byte of a by a[i] (given a is not empty) and the i-th Byte of b by b[i] (given that b is not empty), respectively. Then comparing a and b lexicographically means: Let l := min(n,m). If l is 0 or a[i] = b[i] for all i in [0, l-1], then

  • a is lexicographically less than b if n < m
  • a is lexicographically greater than b if n > m
  • a and b are lexicographically equal if n = m

Otherwise there exists an i in [0, l - 1] such that for all a[j] = b[j] for all j < i holds and a[i] != b[i]. In that case:

  • a is lexicographically less than b if a[i] < b[i]
  • a is lexicographically greater than b if a[i] > b[i]

Arcadia_StringBuilder_getNumberOfBytes

Arcadia_SizeValue
Arcadia_StringBuilder_getNumberOfBytes
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder self
  ) Get the number of Bytes in this string buffer.

Parameters

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

Return value

The number of Bytes in this string buffer.

Arcadia_StringBuilder_insertAt

void
Arcadia_StringBuilder_insertAt
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    Arcadia_SizeValue index,
    Arcadia_Value value
  ) Insert a value at a code point index of string buffer.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_StringBuilder* self
A pointer to this string buffer.
Arcadia_SizeValue index
The code point index at which to insert the value. Must be within the bounds of [0,n] where n is the number of code points in this string buffer. If index is 0, then this call is equivalent to a call to Arcadia_StringBuilder_insertFront. If index is n, then this call is equivalent to a call to Arcadia_StringBuilder_insertBack.
Arcadia_Value value
The value to insert at the code point index. The value must be of one of the following types: Arcadia.ImmutableByteArray, Arcadia.ImmutableUtf8String, Arcadia.ByteBuffer, Arcadia.StringBuilder, or Arcadia.String.

Errors

Arcadia_Status_ArgumentTypeInvalid
value is not of an accepted type.
Arcadia_Status_ArgumentValueInvalid
index is not within the bounds of [0,n] where n is the number of code points in this string buffer.
Arcadia_Status_EncodingInvalid
value is of type Arcadia.ImmutableByteArray or Arcadia.ByteBuffer and the Bytes are not a valid UTF-8 Byte sequence.

Arcadia_StringBuilder_insertBack

void
Arcadia_StringBuilder_insertFront
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    Arcadia_Value value
  ) Insert a 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.
Arcadia_Value value
The value to insert at the back. The value must be of one of the following types: Arcadia.ImmutableByteArray, Arcadia.ImmutableUtf8String, Arcadia.ByteBuffer, Arcadia.StringBuilder, or Arcadia.String.

Errors

Arcadia_Status_ArgumentTypeInvalid
value is not of an accepted type.
Arcadia_Status_EncodingInvalid
value is of type Arcadia.ImmutableByteArray or Arcadia.ByteBuffer and the Bytes are not a valid UTF-8 Byte sequence.

Arcadia_StringBuilder_insertFront

void
Arcadia_StringBuilder_insertFront
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self,
    Arcadia_Value value
  ) Insert a value 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_Value value
The value to insert at the front. The value must be of one of the following types: Arcadia.ImmutableByteArray, Arcadia.ImmutableUtf8String, Arcadia.ByteBuffer, Arcadia.StringBuilder, or Arcadia.String.

Errors

Arcadia_Status_ArgumentTypeInvalid
value is not of an accepted type.
Arcadia_Status_EncodingInvalid
value is of type Arcadia.ImmutableByteArray or Arcadia.ByteBuffer and the Bytes are not a valid UTF-8 Byte sequence.

Arcadia_StringBuilder_isEmpty

Arcadia_BooleanValue
Arcadia_StringBuilder_isEmpty
  (
    Arcadia_Thread* thread,
    Arcadia_StringBuilder* self
  ) Get if this string buffer is empty.

Parameters

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

Return value

Arcadia_BooleanValue_True if this string buffer is empty. Arcadia_BooleanValue_False otherwise.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Numeric functions

Arcadia_ceil*

Type
Arcadia_ceilSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the least integer not less than x.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value to compute the ceil of.

If x is ±0, ±∞, or not a number, then x is returned.

Return value

The ceil of x.

Arcadia_clamp*

Type
Arcadia_clampSuffix
 (
  Arcadia_Thread* thread,
  Type value,
  Type lower,
  Type upper
 ) Clamp a value to a range.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type value
The value to clamp.
Type lower
The lower bound (inclusive).
Type upper
The upper bound (inclusive).

This function returns the value value clamped to the range [lower, upper].

Errors

Arcadia_Status_ArgumentValueInvalid
lower > upper
Arcadia_Status_EncodingInvalid
The sequence of Bytes does not represented a UTF-8-NO-BOM string.

Return value

The value value clamped to the range [lower, upper].

Arcadia_cos*

Type
Arcadia_cosSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the cosine of x.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value to compute the cosine of.

This function returns the cosine of x. If x is ±0 then the result is 1. If x is ±∞ or not a number then the result is not a number.

Return value

The cosine of x.

Arcadia_countLeadingZeroes*

Arcadia_SizeValue
Arcadia_countLeadingZeroesSuffix
 (
  Arcadia_Thread* thread,
  Type value
 ) Return the number of leading zeroes of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function returns the number of leading zeroes of the binary representation of value.

Parameters
Arcadia_Thread* threadA pointer to the Arcadia_Thread object.
Type valueThe value.
Return value

The number of leading zeroes.

Arcadia_countSignificandBits*

Arcadia_SizeValue
Arcadia_countSignificandBitsSuffix
 (
  Arcadia_Thread* thread,
  Type value
 ) Get the number of significand Bits of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function returns the number of significand Bits of the binary representation of value.

Parameters
Arcadia_Thread* threadA pointer to the Arcadia_Thread object.
Type valueThe value.
Return value

The number of significand Bits.

Arcadia_countTrailingZeroes*

Arcadia_SizeValue
Arcadia_countTrailingZeroesSuffix
 (
  Arcadia_Thread* thread,
  Type value
 ) Return the number of trailing zeroes of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function returns the number of trailing zeroes of the binary representation of value.

Parameters
Arcadia_Thread* threadA pointer to the Arcadia_Thread object.
Type valueThe value.
Return value

The number of leading zeroes.

Arcadia_floor*

Type
Arcadia_floorSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the greatest integer value not greater than x.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value to compute the floor of.

If x is ±0, ±∞, or not a number, then x is returned.

Return value

The floor of x.

Arcadia_hash*

Arcadia_SizeValue
Arcadia_hashSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the hash of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
BooleanValue Arcadia_BooleanValue
ForeignProcedureValueArcadia_ForeignProcedureValue
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value
SizeValue Arcadia_SizeValue
VoidValue Arcadia_VoidValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Return value

Return hash of x.

Arcadia_isPowerOfTwo*

Arcadia_BooleanValue
Arcadia_isPowerOfTwoSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Get if a value is a power of two.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Return value

Arcadia_BooleanValue_True if the value x/ is a power of two. Arcadia_BooleanValue_False otherwise.

Arcadia_maximum*

Type
Arcadia_maximumSuffix
 (
  Arcadia_Thread* thread,
  Type x,
  Type y
 ) Return the maximum of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Integer8ValueArcadia_Integer8Value
Integer16ValueArcadia_Integer16Value
Integer32ValueArcadia_Integer32Value
Integer64ValueArcadia_Integer64Value
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The first value.
Type y
The second value.

Return value

Return the maximum of x and y.

Arcadia_minimum*

Type
Arcadia_minimumSuffix
 (
  Arcadia_Thread* thread,
  Type x,
  Type y
 ) Compute the minimum of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8ValueArcadia_Integer8Value
Integer16ValueArcadia_Integer16Value
Integer32ValueArcadia_Integer32Value
Integer64ValueArcadia_Integer64Value
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The first value.
Type y
The second value.

Return value

Return the minimum of x and y.

Arcadia_nextPowerOfTwoGreaterThan*

Type
Arcadia_nextPowerOfTwoGreaterThanSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Get the next power of two greater than a specified value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Errors

Arcadia_Status_NotExists
The next power of two greater than x is not representable by the type Type

Return value

Return the next power of two greater than x.

Arcadia_nextPowerOfTwoGreaterThanOrEqualTo*

Type
Arcadia_nextPowerOfTwoGreaterThanOrEqualToSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the next power of two greater then or equal to a specified value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Errors

Arcadia_Status_NotExists
The next power of two greater greater than or equal to x is not representable by the type Type

Return value

Return the next power of two greater than or equal to x.

Arcadia_quotientRemainder*

void
Arcadia_quotientRemainderSuffix
 (
  Arcadia_Thread* thread,
  Type dividend,
  Type divisor,
  Type* quotient,
  Type* remainder
 ) Return the number of significand Bits of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function computes the quotient q = dividend / divisor and the remainder r = dividend - (q * divisor). The quotient is stored in *quotient and the divisor is stored in *remainder.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type dividend
The dividend.
Type divisor
The divisor.
Type quotient
Variable to store the quotient in.
Type remainder
Variable to store the remainder in.

Errors

Arcadia_Status_ArgumentValueInvalid
quotient or remainder is zero.
Arcadia_Status_DivisionByZero
The divisor is zero.

Arcadia_safeAddFull*

void
Arcadia_safeAddFullSuffix
 (
  Arcadia_Thread* thread,
  Type augend,
  Type addend,
  Type* sumHigh,
  Type* sumLow
 ) Compute the sum of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
Natural8Value Arcadia_Natural8Value
SizeValue Arcadia_SizeValue
Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type augend
The augend value.
Type addend
The addend value.
Type* sumHigh
A pointer to a variable. The variable is assigned the high bits of the result.
Type* sumLow
A pointer to a variable. The variable is assigned the low bits of the result.

Arcadia_safeMultiply*

void
Arcadia_safeMultiplySuffix
 (
  Arcadia_Thread* thread,
  Type x,
  Type y
 ) Compute the product of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The first value.
Type y
The second value.

Return value

Return the maximum of x and y.

Arcadia_sin*

Type
Arcadia_sinSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the sine of x.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value to compute the sine of.

This function returns the sine of x. If x is ±0 then the result is 0. If x is ±∞ or not a number then the result is not a number.

Return value

The sine of x.

Arcadia_sqrt*

Type
Arcadia_sqrtSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the square root of x.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value to compute the square root of.

This function returns the square root of x. If x is less than -0 or not a number, then not a number os returned. If x is +∞ or ±∞0, then x is returned unmodified.

Return value

The square root of x.

Arcadia_Real*Value_getBits

Arcadia_NaturalBits
Arcadia_RealBitsValue_getBits
(
Arcadia_Thread* thread,
Arcadia_RealBitsValue self
) Get the bits of an Arcadia_RealSuffixValue where Suffix denotes the number of Bits of the type and can be one of 32 or 64.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_RealBits self
The Real value.

Return value

Return the bits of the Real value as a Natural value.

Time and date functions

Arcadia_getTickCount

Arcadia_Natural64Value
Arcadia_getTickCount
 (
  Arcadia_Thread* thread
 ) Get the time, in milliseconds, since an unspecified moment in the past.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.

Return value

The time, in milliseconds, since an unspecified momentn in the past.

Unicode functions

Arcadia_Unicode_EncodeCodePointCallbackContext

typedef void Arcadia_Unicode_EncodeCodePointCallbackContext; Arcadia_Unicode_EncodeCodePointCallbackContext* to denote an opaque pointer passed as a callback.

Arcadia_EncodeCodePointCallbackFunction

typedef void
(Arcadia_EncodeCodePointCallbackFunction)
 (
  Arcadia_Thread* thread,
  Arcadia_EncodeCodePointCallbackContext* context,
  const Arcadia_Natural8Value* bytes,
  Arcadia_SizeValue numberOfBytes
 ) The type of a function receiving an encoding of an Unicode code point.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_EncodeCodePointCallbackContext* context
An opaque context pointer passed to invocations of the callback function.
const Arcadia_Natural8Value* bytes
A pointer to an array of numberOfBytes Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array of Bytes pointed to by bytes.

Arcadia_encodeCodePointsUtf8

void
Arcadia_encodeCodePointUtf8
 (
  Arcadia_Thread* thread,
  const Arcadia_Natural32Value* codePoints,
  Arcadia_SizeValue numberOfCodePoints,
  Arcadia_EncodeCodePointCallbackContext* context,
  Arcadia_EncodeCodePointCallbackFunction* function
 ) Encode Unicode code points as an UTF-8 Byte sequence.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Natural32Value* codePoints
A pointer to an array of numberOfCodePoints Arcadia_Natural32Value values. Each Arcadia_Natural32Value in the range of a Unicode code point.
Arcadia_SizeValue numberOfCodePoints
The number of Arcadia_Natural32Value in the array pointed to by codePoints.
Arcadia_EncodeCodePointCallbackContext* context
The callback context.
Arcadia_EncodeCodePointCallbackFunction* function
The callback function.

Errors

Arcadia_Status_EncodingInvalid
codePoint does not represent an Unicode code point
Arcadia_Status_ArgumentValueInvalid
codePoints is a null pointer
Arcadia_Status_ArgumentValueInvalid
codePoints is a null pointer

Arcadia_Unicode_isUTF8

Arcadia_BooleanValue
Arcadia_Unicode_isUTF8
 (
  Arcadia_Thread* thread,
  const void* bytes,
  Arcadia_SizeValue numberOfBytes,
  Arcadia_SizeValue* numberOfSymbols
 ) Get if a sequence of Bytes is an UTF-8 sequence of Bytes and count its number of symbols.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
const void* bytes
A pointer to an array of numberOfBytes Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array of Bytes pointed to by bytes.
Arcadia_SizeValue* numberOfSymbols
The number of Bytes in the array of Bytes pointed to by bytes. If this function terminates and this pointer is not null, the variable is assigned the number of symbols decoded successfully so far.

Return value

Arcadia_BooleanValue_True if the sequence of numberOfBytes Bytes pointed to by bytes is an UTF-8 sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Memory functions

Arcadia_Memory_allocateUnmanaged

void*
Arcadia_Memory_allocateUnmanaged
 (
  Arcadia_Thread* thread
 ) Allocate an unnamanged memory region.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_SizeValue size
The size, in Bytes, of the memory region to allocate. Memory regions of zero Bytes are supported.

Return value

A pointer to the first Byte of the memory region.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Arcadia_Memory_compare

Arcadia_Integer8Value
Arcadia_Memory_compare
 (
  Arcadia_Thread* thread,
  const void* p,
  const void* q,
  Arcadia_SizeValue n
 ) Compare two memory regions.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
const void* p
A pointer to the first Byte of the first memory region.
const void* q
A pointer to the first Byte of the second memory region.
Arcadia_SizeValue n
The number of Bytes to compare.

Return value

A positive value if the first memory region is greater than the first memory region. A negative value if the first memory region is less than the second memory region. Zero if both memory regions are equal.

Remarks

A memory region (p,n) is equal to a memory region (q,n) if for all 0<e; i < p[i] = q[i] holds. Otherwise there exists a least 0<e; i < n such that p[i] &neq; q[i] holds and consequently either p[i] < q[i] or p[i] > q[i] holds: if p[i] &neq; q[i] holds then p is less than q and if p[i] > q[i] holds then p is greater than q.

Arcadia_Memory_copy

void
Arcadia_Memory_copy
 (
  Arcadia_Thread* thread,
  void* target,
  const void* source,
  Arcadia_SizeValue numberOfBytes
 ) Copy the Bytes from one memory region to another memory region. The memory regions may overlap.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
void* target
A pointer to the first Byte of the target memory region.
const void* source
A pointer to the first Byte of the source memory region.
Arcadia_SizeValue numberOfBytes
The number of Bytes to copy.

Arcadia_Memory_deallocateUnmanaged

void
Arcadia_Memory_deallocateUnmanaged
 (
  Arcadia_Thread* thread,
  void* p
 ) Deallocate an unmanaged region of memory.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
void* p
A pointer to the first Byte of the memory region.

Arcadia_Memory_fill

void
Arcadia_Memory_fill
 (
  Arcadia_Thread* thread,
  void* bytes,
  Arcadia_SizeValue numberOfBytes
  Arcadia_Natural8Value value
 ) Assignt the Bytes of a memory region a value.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
void* p
A pointer to the first Byte of the target memory region.
Arcadia_SizeValue n
The size, in Bytes, of the memory region.
Arcadia_Natural8Value v
The value to assign to each Byte of the memory region.

Arcadia_Memory_reallocateUnmanaged

void*
Arcadia_Memory_reallocateUnmanaged
 (
  Arcadia_Thread* thread
 ) Reallocate a memory region.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
void* p
A pointer to the first Byte of the old memory region.
Arcadia_SizeValue n
The size, in Bytes, of the new memory region.

Return value

A pointer to the first Byte of the new memory region.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Remarks

The succesful reallocation of a memory region (p,n) to a memory region (q,m) effectively means: The old memory region p of size n was deallocated, the new memory region q of size m was allocated. Furthermore, the first bytes k = min(n,m) Bytes of the old memory region and the new memory region have the same values.

If the reallocation fails, then the memory region (p,n) is not modified.

Miscellaneous functions

Arcadia_getNumberOfCores

Arcadia_Natural64Value
Arcadia_getNumberOfCores
 (
  Arcadia_Thread* thread
 ) Get the number of CPU cores.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.

Return value

The number of CPU cores.

Arcadia_getPageSize

Arcadia_Natural64Value
Arcadia_getPageSize
 (
  Arcadia_Thread* thread
 ) Get the memory page size.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.

Return value

The memory page size.

Arcadia_Configuration_CompilerC

#define Arcadia_Configuration_CompilerC /* implementation */ Symbolic constant denoting the C compiler used for compiling this program. It is always defined to one of the Arcadia_Configuration_CompilerC_* constants.

Arcadia_Configuration_CompilerC_Gcc

#define Arcadia_Configuration_CompilerC_Gcc /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_CompilerC_* symbol constants. This symbolic constant denotes the GCC C compiler.

Arcadia_Configuration_CompilerC_Clang

#define Arcadia_Configuration_CompilerC_Clang /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_CompilerC_* symbol constants. This symbolic constant denotes the CLANG C compiler.

Arcadia_Configuration_CompilerC_Msvc

#define Arcadia_Configuration_CompilerC_Gcc /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_CompilerC_* symbol constants. This symbolic constant denotes the MSVC C compiler.

Arcadia_Configuration_Version_Major

#define Arcadia_Configuration_Version_Major /* implementation */ Symbolic constant defined to a non-negative integer value. This value denotes the major version number of this program.

Arcadia_Configuration_Version_Major

#define Arcadia_Configuration_Version_Major /* implementation */ Symbolic constant defined to a non-negative integer value. This value denotes the minor version number of this program.

Arcadia_Configuration_OperatingSystem_Cygwin

#define Arcadia_Configuration_OperatingSystem_Cygwin /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes the CYGWIN operating system.

Arcadia_Configuration_OperatingSystem_Ios

#define Arcadia_Configuration_OperatingSystem_Ios /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes the IOS operating system.

Arcadia_Configuration_OperatingSystem_IosEmulator

#define Arcadia_Configuration_OperatingSystem_IosEmulator /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes the IOS EMULATOR operating system.

Arcadia_Configuration_OperatingSystem_Linux

#define Arcadia_Configuration_OperatingSystem_Linux /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes the LINUX operating system.

Arcadia_Configuration_OperatingSystem_Macos

#define Arcadia_Configuration_OperatingSystem_Macos /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes the MACOS operating system.

Arcadia_Configuration_OperatingSystem_Mingw

#define Arcadia_Configuration_OperatingSystem_Mingw /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes a MINGW operating system.

Arcadia_Configuration_OperatingSystem_Msys

#define Arcadia_Configuration_OperatingSystem_Msys /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes an MSYS operating system.

Arcadia_Configuration_OperatingSystem_Unix

#define Arcadia_Configuration_OperatingSystem_Unix /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes a UNIX operating system.

Arcadia_Configuration_OperatingSystem_Windows

#define Arcadia_Configuration_OperatingSystem_Windows /* implementation */ Symbolic constant defined to an integer value that is different from the values of all other Arcadia_Configuration_OperatingSystem_* symbol constants. This symbolic constant denotes the WINDOWS operating system.

Annotations

Arcadia_Likely

#define Arcadia_Likely(expression) implementation detail Expression annotation aiding branch prediction by indicating an expression is likely to evaluate to logically true.

Parameters

expression
An expression.

For example, given typical programs, it is likely that malloc for a small size of memory is very likely to succeed. Hence, in the following code snipped, we tell tell the compiler that the test for success of a call to malloc is likely to to evaluate to logically true and the code in branch (A) is likely to be executed whilst consequently the code in branch (X) is not likely to be execute.

void* p = malloc(sizeof(char));
if (Arcadia_Likely(p)) {
/* (A) Foaming with joy, continue execution. */
} else {
/* (X) In the heart with pain, abort execution. */
}

Arcadia_NoReturn

#define Arcadia_NoReturn() implementation detail Function annotation indicating a function does not return.

Arcadia_ThreadLocal

#define Arcadia_ThreadLocal() implementation detail Variable annotation indicating thread local storage.

Arcadia_Unlikely

#define Arcadia_Unlikely(expression) implementation detail Expression annotation aiding branch prediction by indicating an expression is unlikely to evaluate to logically true.

Parameters

expression
An expression.

For example, given typical programs, it is likely that malloc for a small size of memory is very likely to succeed. Hence, in the following code snipped, we tell tell the compiler that the test for failure of a call to malloc is likely to to evaluate to logically false and the code in branch (A) is likely to be executed whilst consequently the code in branch (X) is not likely to be execute.

char *p = malloc(sizeof(char));
if (Arcadia_Unlikely(!p)) {
/* (X) In the heart with pain, abort execution. */
} else {
/* (A) Foaming with joy, continue execution. */
}