view release on metacpan or  search on metacpan

cfcore/Clownfish/String.cfh  view on Meta::CPAN

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

parcel Clownfish;

__C__

// For strlen
#include <string.h>

// For CFISH_ALLOCA_OBJ.
#include "Clownfish/Class.h"

// For CFISH_ERR_FUNC_MACRO.
#include "Clownfish/Err.h"

__END_C__

/**
 * Immutable string holding Unicode characters.
 */

public final class Clownfish::String nickname Str
    inherits Clownfish::Obj {

    const char *ptr;
    size_t      size;
    String     *origin;

    /** Return true if the string is valid UTF-8, false otherwise.
     */
    public inert bool
    utf8_valid(const char *ptr, size_t len);

    /** Throws an error if the string isn't valid UTF-8.
     */
    public inert void
    validate_utf8(const char *text, size_t size, const char *file, int line,
                  const char *func);

    /** Returns true if the code point qualifies as Unicode whitespace.
     */
    public inert bool
    is_whitespace(int32_t code_point);

    /** Encode a Unicode code point to a UTF-8 sequence.
     *
     * @param code_point A legal unicode code point.
     * @param buffer Write buffer which must hold at least 4 bytes (the
     * maximum legal length for a UTF-8 char).
     */
    inert uint32_t
    encode_utf8_char(int32_t code_point, void *buffer);

    /** Return a String which holds a copy of the supplied UTF-8 character
     * data after checking for validity.
     *
     * @param utf8 Pointer to UTF-8 character data.
     * @param size Size of UTF-8 character data in bytes.
     */
    public inert incremented String*
    new_from_utf8(const char *utf8, size_t size);

    /** Return a String which holds a copy of the supplied UTF-8 character
     * data, skipping validity checks.
     *
     * @param utf8 Pointer to UTF-8 character data.
     * @param size Size of UTF-8 character data in bytes.
     */
    public inert incremented String*
    new_from_trusted_utf8(const char *utf8, size_t size);

    /** Initialize a String which holds a copy of the supplied UTF-8 character
     * data, skipping validity checks.
     *
     * @param utf8 Pointer to UTF-8 character data.
     * @param size Size of UTF-8 character data in bytes.
     */
    public inert String*
    init_from_trusted_utf8(String *self, const char *utf8, size_t size);

    /** Return a String which assumes ownership of the supplied buffer
     * containing UTF-8 character data after checking for validity.
     *
     * @param utf8 Pointer to UTF-8 character data.
     * @param size Size of UTF-8 character data in bytes.
     */
    public inert incremented String*
    new_steal_utf8(char *utf8, size_t size);

    /** Return a String which assumes ownership of the supplied buffer
     * containing UTF-8 character data, skipping validity checks.
     *
     * @param utf8 Pointer to UTF-8 character data.
     * @param size Size of UTF-8 character data in bytes.
     */
    public inert incremented String*
    new_steal_trusted_utf8(char *utf8, size_t size);

    /** Initialize a String which assumes ownership of the supplied buffer
     * containing UTF-8 character data, skipping validity checks.
     *
     * @param utf8 Pointer to UTF-8 character data.
     * @param size Size of UTF-8 character data in bytes.
     */
    public inert String*
    init_steal_trusted_utf8(String *self, char *utf8, size_t size);