strings.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
#pragma once
 
#include <stddef.h>
#include <stdint.h>
 
// TODO(lxsameer): Implement the WTF8 support based on Rust's implementation
 
typedef struct srn_context_t srn_context_t;
typedef struct srn_error_t srn_error_t;
typedef struct srn_value_t srn_value_t;
typedef struct srn_metadata_t srn_metadata_t;
 
// TODO(lxsameer): Decide how this type supports Unicode.
//
// Encoding. Strict UTF-8 keeps every live string valid Unicode by invariant
// and IO needs no exit checks, ill formed input is rejected or lossily
// converted at entry. WTF-8 is UTF-8 plus unpaired surrogates and exists to
// round trip ill formed UTF-16 (Windows paths, JS strings), the cost is a
// sanitize or reject step at every IO boundary. A third shape is two types,
// strict UTF-8 for language strings plus a separate OS string type for FFI
// with explicit conversions (the Rust String/OsString split).
//
// Validation. Validate at construction (srn_string_make and the reader)
// returning error values, so validity is an invariant of the type and
// nothing downstream revalidates. Trusting pre validated input instead is
// what makes the vendored utf8.h dangerous.
//
// Length. Bytes stay the primitive. The user facing length can be bytes
// only, or bytes plus a code point count cached during the validation pass
// (O(1) length, iteration instead of integer indexing), or grapheme
// clusters, which need Unicode segmentation tables and belong in a library
// rather than the runtime.
//
// Implementation. A strict validator and decoder is roughly fifty lines as
// a DFA (Hoehrmann's design is the standard reference), total and
// allocation free. utf8proc only earns its place if normalization, case
// folding, or grapheme segmentation move into the runtime.
//
// Symbol identity. Precomposed and combining spellings of the same text are
// different byte sequences, so byte identity interning treats them as two
// symbols. Normalizing identifiers at read time fixes that at the price of
// normalization tables in the reader. Whichever wins belongs in the spec.
typedef struct srn_string_t {
  /// Size of the buffer
  size_t size;
  /// length of the WTF-8 sequence in bytes
  size_t len;
  /// The buffer that holds the WTF8 sequence.
  uint8_t buffer[];
} srn_string_t;
 
/// Create a string from a null terminated C string. IT HAS TO BE NULL
/// TERMINATED
[[gnu::nonnull(1)]]
srn_value_t *srn_string_make(srn_context_t *ctx, srn_metadata_t *metadata, const char *src);
 
[[gnu::nonnull(1)]]
size_t srn_string_size(const srn_string_t *s);
[[gnu::nonnull(1)]]
size_t srn_string_length(const srn_string_t *s);
 
/// Allocate a copy of `src` through `ctx` and return it.
[[gnu::nonnull(1, 2)]]
srn_string_t *srn_string_copy(srn_context_t *ctx, const srn_string_t *src);
 
bool srn_string_is_empty(const srn_string_t *s);
bool srn_string_eq(const srn_string_t *a, const srn_string_t *b);