Str operations

Several operations are provided for dealing with string objects. The operations include creating string objects, converting between different string encodings, reading the contents of strings and creating substrings.

See also: You can use the AAdd function to concatenate strings. String methods such as strip can be called using ACallMethod.

Creating

AValue AMakeStr(AThread *t, const char *str)

Create a std::Str object from a a zero-terminated 8-bit string. The character values in the argument are mapped to range 1 to 255 in the result. Raise a direct exception on all error conditions.

AValue AMakeStrW(AThread *t, const AWideChar *str)

Create a std::Str object from a zero-terminated 16-bit string. Raise a direct exception on all error conditions.

AValue AMakeStrUtf8(AThread *t, const char *str)

Create a std::Str object from a UTF-8 encoded string. The result is a 16-bit string. Raise a direct exception on all error conditions.

AValue AMakeCh(AThread *t, AWideChar ch)

Create a 1-element std::Str object from a character code. Any character code in range 0 to 65535 is valid. Raise a direct exception on all error conditions.

AValue AMakeEmptyStr(AThread *t, Assize_t len)

Create a uninitialized std::Str object with the specified length. You must initialize the entire contents of the string using ASetStrItem or AStrPtr before exposing the object to Alore code. You must only use 8-bit character codes, i.e. character values between 0 and 255, when initializing the string. Raise a direct exception on all error conditions.

AValue AMakeEmptyStrW(AThread *t, Assize_t len)

Create a uninitialized std::Str object with the specified length. You must initialize the entire contents of the string using ASetStrItem or AStrPtrW before exposing the object to Alore code. Raise a direct exception on all error conditions.

void ASetStrItem(AValue string, int index, AWideChar ch)

Initialize a character within a string at given index to value ch. Only strings created using AMakeEmptyStr or AMakeEmptyStrW can be initialized using this function. The index (0-based) must be non-negative and less than the length of the string. After a string has been initialized, its contents must not be changed. This function performs no error checking.

unsigned char *AStrPtr(AValue string)

Return a pointer to the contents of a string object created using AMakeEmptyStr. This pointer can be used to initialize the contents of the string. Any operation that may cause the garbage collector to run will invalidate the pointer. You must not store a zero terminator in the string or write past the end of the buffer. The size of the buffer is defined by the length of the string.

AWideChar *AStrPtrW(AValue string)

Return a pointer to the contents of a string object created using AMakeEmptyStrW. This pointer can be used to initialize the contents of the string. Any operation that may cause the garbage collector to run will invalidate the pointer. You must not store a zero terminator in the string or write past the end of the buffer. The size of the buffer is defined by the length of the string.

AValue AToStr(AThread *t, AValue object)

Return the string value of an object, equivalent to the valued produced by the call std::Str(object).

Reading

Assize_t AStrLen(AValue string)

Return the length of a string. The argument must be a std::Str object, since this function performs no error checking.

AWideChar AStrItem(AValue string, Assize_t index)

Return the value of a character in a string. The argument must be a std::Str object, and the index (0-based) must be non-negative and less than the length of the string. This function performs no error checking.

Assize_t AGetStr(AThread *t, AValue v, char *buf, Assize_t bufLen)

Store the contents of a Str object in a 8-bit buffer as a zero-terminated string. The bufLen argument specifies the size of the buffer. Return the length of the string, without the zero terminator. Raise an exception if the value does not refer to a Str, if the buffer is too small to contain the string contents and the zero terminator, or if the string contains character values larger than 255. Raise a direct exception on all error conditions.

Assize_t AGetStrW(AThread *t, AValue v, AWideChar *buf, Assize_t bufLen)

Store the contents of a Str object in a 16-bit buffer as a zero-terminated string. The bufLen argument specifies the size of the buffer. Return the length of the string, without the zero terminator. Raise an exception if the value does not refer to a Str or if the buffer is too small to contain the string contents and the zero terminator. Raise a direct exception on all error conditions.

Assize_t AGetStrUtf8(AThread *t, AValue v, char *buf, Assize_t bufLen)

Store the contents of a Str object in a 8-bit buffer as a zero-terminated UTF-8 encoded string. The bufLen argument specifies the size of the buffer. Return the length of the encoded string, without the zero terminator. Raise an exception if the value does not refer to a Str or if the buffer is too small to contain the encoded string contents and the zero terminator. Raise a direct exception on all error conditions.

Assize_t AStrLenUtf8(AValue string)

Return the length of resulting string when a string is UTF-8 encoded, without actually performing the encoding, not including the zero terminator. The argument must be a std::Str object, since this function performs no error checking.

AValue ASubStr(AThread *t, AValue v, Assize_t i1, Assize_t i2)

Return the substring i1:i2 of a string. The rules for indices are similar to when indexing substrings in Alore code, and negative indices are supported. As an exception, the constant A_SLICE_END as the end index specifies a substring extending to the end of the string. Raise a direct exception on all error conditions.

AWideChar AGetCh(AThread *t, AValue v)

If the argument is a Str object of length 1, return the character value of the string. Otherwise, raise an exception. Raise a direct exception on all error conditions.

Checking

ABool AIsStr(AValue v)

Return a boolean indicating whether v is a std::Str object.

void AExpectStr(AThread *t, AValue v)

Check if v is a Str object and raise a direct std::TypeError exception if it is not.