nanocoat/include/sjme/charSeq.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Character sequences.
  12  *
  13  * @since 2024/06/26
  14  */
  15
  16 #ifndef SQUIRRELJME_CHARSEQ_H
  17 #define SQUIRRELJME_CHARSEQ_H
  18
  19 #include "sjme/nvm.h"
  20
  21 /* Anti-C++. */
  22 #ifdef __cplusplus
  23         #ifndef SJME_CXX_IS_EXTERNED
  24                 #define SJME_CXX_IS_EXTERNED
  25                 #define SJME_CXX_SQUIRRELJME_CHARSEQ_H
  26 extern "C" {
  27         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  28 #endif     /* #ifdef __cplusplus */
  29
  30 /*--------------------------------------------------------------------------*/
  31
  32 /**
  33  * A character sequence which contains a set of characters within a string,
  34  * may be modifiable or not.
  35  *
  36  * @since 2024/06/26
  37  */
  38 typedef struct sjme_charSeq sjme_charSeq;
  39
  40 /**
  41  * Returns the character at the given index.
  42  *
  43  * @param inSeq The input character sequence.
  44  * @param inIndex The index to get from.
  45  * @param outChar The resultant character.
  46  * @return Any resultant error, if any.
  47  * @since 2024/06/27
  48  */
  49 typedef sjme_errorCode (*sjme_charSeq_charAtFunc)(
  50         sjme_attrInNotNull const sjme_charSeq* inSeq,
  51         sjme_attrInPositive sjme_jint inIndex,
  52         sjme_attrOutNotNull sjme_jchar* outChar);
  53
  54 /**
  55  * Deletes the given static character sequence.
  56  *
  57  * @param inSeq The input/output sequence.
  58  * @return Any resultant error, if any.
  59  * @since 2024/06/26
  60  */
  61 typedef sjme_errorCode (*sjme_charSeq_deleteFunc)(
  62         sjme_attrInNotNull sjme_charSeq* inSeq);
  63
  64 /**
  65  * Returns the length of the character sequence.
  66  *
  67  * @param inSeq The input character sequence.
  68  * @param outLen The sequence length.
  69  * @return Any resultant error, if any.
  70  * @since 2024/06/27
  71  */
  72 typedef sjme_errorCode (*sjme_charSeq_lengthFunc)(
  73         sjme_attrInNotNull const sjme_charSeq* inSeq,
  74         sjme_attrOutNotNull sjme_jint* outLen);
  75
  76 /**
  77  * Functions which are used to process character sequences.
  78  *
  79  * @since 2024/06/26
  80  */
  81 typedef struct sjme_charSeq_functions
  82 {
  83         /** The character at the given index. */
  84         sjme_charSeq_charAtFunc charAt;
  85
  86         /** Deleting the sequence and freeing any resources. */
  87         sjme_charSeq_deleteFunc delete;
  88
  89         /** The length of the character sequence. */
  90         sjme_charSeq_lengthFunc length;
  91 } sjme_charSeq_functions;
  92
  93 struct sjme_charSeq
  94 {
  95         /** Front end data, if any. */
  96         sjme_frontEnd frontEnd;
  97
  98         /** Context pointer, if any. */
  99         sjme_pointer context;
 100
 101         /** The API for accessing the character sequence. */
 102         const sjme_charSeq_functions* impl;
 103 };
 104
 105 /**
 106  * Returns the character at the given index.
 107  *
 108  * @param inSeq The input character sequence.
 109  * @param inIndex The index to get from.
 110  * @param outChar The resultant character.
 111  * @return Any resultant error, if any.
 112  * @since 2024/06/27
 113  */
 114 sjme_errorCode sjme_charSeq_charAt(
 115         sjme_attrInNotNull const sjme_charSeq* inSeq,
 116         sjme_attrInPositive sjme_jint inIndex,
 117         sjme_attrOutNotNull sjme_jchar* outChar);
 118
 119 /**
 120  * Deletes the given static character sequence.
 121  *
 122  * @param inOutSeq The input/output sequence.
 123  * @return Any resultant error, if any.
 124  * @since 2024/06/26
 125  */
 126 sjme_errorCode sjme_charSeq_deleteStatic(
 127         sjme_attrInNotNull sjme_charSeq* inOutSeq);
 128
 129 /**
 130  * Returns the length of the character sequence.
 131  *
 132  * @param inSeq The input character sequence.
 133  * @param outLen The sequence length.
 134  * @return Any resultant error, if any.
 135  * @since 2024/06/27
 136  */
 137 sjme_errorCode sjme_charSeq_length(
 138         sjme_attrInNotNull const sjme_charSeq* inSeq,
 139         sjme_attrOutNotNull sjme_jint* outLen);
 140
 141 /**
 142  * Initializes the given static character sequence.
 143  *
 144  * @param inOutSeq The input/output sequence.
 145  * @param inFunctions The input functions for the character sequence.
 146  * @param inOptContext The context to set.
 147  * @param inOptFrontEnd The front end data to copy.
 148  * @return Any resultant error, if any.
 149  * @since 2024/06/27
 150  */
 151 sjme_errorCode sjme_charSeq_newStatic(
 152         sjme_attrInNotNull sjme_charSeq* inOutSeq,
 153         sjme_attrInNotNull const sjme_charSeq_functions* inFunctions,
 154         sjme_attrInNullable sjme_pointer inOptContext,
 155         sjme_attrInNullable sjme_frontEnd* inOptFrontEnd);
 156
 157 /**
 158  * Creates a character sequence that accesses the given standard C string
 159  * as Utf characters.
 160  *
 161  * @param inOutSeq The resultant sequence.
 162  * @param inString The string to wrap.
 163  * @return Any resultant error, if any.
 164  * @since 2024/07/26
 165  */
 166 sjme_errorCode sjme_charSeq_newUtfStatic(
 167         sjme_attrInNotNull sjme_charSeq* inOutSeq,
 168         sjme_attrInNotNull sjme_lpcstr inString);
 169
 170 /*--------------------------------------------------------------------------*/
 171
 172 /* Anti-C++. */
 173 #ifdef __cplusplus
 174         #ifdef SJME_CXX_SQUIRRELJME_CHARSEQ_H
 175 }
 176                 #undef SJME_CXX_SQUIRRELJME_CHARSEQ_H
 177                 #undef SJME_CXX_IS_EXTERNED
 178         #endif /* #ifdef SJME_CXX_SQUIRRELJME_CHARSEQ_H */
 179 #endif     /* #ifdef __cplusplus */
 180
 181 #endif /* SQUIRRELJME_CHARSEQ_H */