@head
@title 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 You can use the @ref{AAdd} function to concatenate strings. String methods
such as strip can be called using @ref{ACallMethod}.
@end
Creating
@fun AValue AMakeStr(AThread *t, const char *str)
@desc 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-direct
@end
@fun AValue AMakeStrW(AThread *t, const AWideChar *str)
@desc Create a std::Str object from a zero-terminated 16-bit string.
@raise-direct
@end
@fun AValue AMakeStrUtf8(AThread *t, const char *str)
@desc Create a std::Str object from a UTF-8 encoded string. The result
is a 16-bit string. @raise-direct
@end
@fun AValue AMakeCh(AThread *t, AWideChar ch)
@desc Create a 1-element std::Str object from a character code. Any
character code in range 0 to 65535 is valid. @raise-direct
@end
@fun AValue AMakeEmptyStr(AThread *t, Assize_t len)
@desc Create a uninitialized std::Str object with the specified
length. You must initialize the entire contents of the string using
@ref{ASetStrItem} or @ref{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-direct
@end
@fun AValue AMakeEmptyStrW(AThread *t, Assize_t len)
@desc Create a uninitialized std::Str object with the specified
length. You must initialize the entire contents of the string using
@ref{ASetStrItem} or @ref{AStrPtrW} before exposing the object to Alore
code.
@raise-direct
@end
@fun void ASetStrItem(AValue string, int index, AWideChar ch)
@desc 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.
@end
@fun unsigned char *AStrPtr(AValue string)
@desc Return a pointer to the contents of a string object created using
@ref{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.
@end
@fun AWideChar *AStrPtrW(AValue string)
@desc Return a pointer to the contents of a string object created using
@ref{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.
@end
@fun AValue AToStr(AThread *t, AValue object)
@desc Return the string value of an object, equivalent to the valued produced
by the call std::Str(object).
@end
Reading
@fun Assize_t AStrLen(AValue string)
@desc Return the length of a string.
The argument must be a std::Str object, since this function
performs no error checking.
@end
@fun AWideChar AStrItem(AValue string, Assize_t index)
@desc 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.
@end
@fun Assize_t AGetStr(AThread *t, AValue v, char *buf, Assize_t bufLen)
@desc 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-direct
@end
@fun Assize_t AGetStrW(AThread *t, AValue v, AWideChar *buf, Assize_t bufLen)
@desc 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-direct
@end
@fun Assize_t AGetStrUtf8(AThread *t, AValue v, char *buf, Assize_t bufLen)
@desc 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-direct
@end
@fun Assize_t AStrLenUtf8(AValue string)
@desc 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.
@end
@fun AValue ASubStr(AThread *t, AValue v, Assize_t i1, Assize_t i2)
@desc 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-direct
@end
@fun AWideChar AGetCh(AThread *t, AValue v)
@desc If the argument is a Str object of length 1, return the
character value of the string. Otherwise, raise an exception.
@raise-direct
@end
Checking
@fun ABool AIsStr(AValue v)
@desc Return a boolean indicating whether v is a std::Str object.
@end
@fun void AExpectStr(AThread *t, AValue v)
@desc Check if v is a Str object and raise a direct
@ref{std::TypeError} exception if it is not.
@end