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/frontEnd.h"
  20 #include "sjme/stdTypes.h"
  21 #include "sjme/error.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_CHARSEQ_H
  28 extern "C" {
  29         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  30 #endif     /* #ifdef __cplusplus */
  31
  32 /*--------------------------------------------------------------------------*/
  33
  34 /**
  35  * A character sequence which contains a set of characters within a string,
  36  * may be modifiable or not.
  37  *
  38  * @since 2024/06/26
  39  */
  40 typedef struct sjme_charSeq sjme_charSeq;
  41
  42 /**
  43  * Returns the character at the given index.
  44  *
  45  * @param inSeq The input character sequence.
  46  * @param inIndex The index to get from.
  47  * @param outChar The resultant character.
  48  * @return Any resultant error, if any.
  49  * @since 2024/06/27
  50  */
  51 typedef sjme_errorCode (*sjme_charSeq_charAtFunc)(
  52         sjme_attrInNotNull const sjme_charSeq* inSeq,
  53         sjme_attrInPositive sjme_jint inIndex,
  54         sjme_attrOutNotNull sjme_jchar* outChar);
  55
  56 /**
  57  * Deletes the given static character sequence.
  58  *
  59  * @param inSeq The input/output sequence.
  60  * @return Any resultant error, if any.
  61  * @since 2024/06/26
  62  */
  63 typedef sjme_errorCode (*sjme_charSeq_deleteFunc)(
  64         sjme_attrInNotNull sjme_charSeq* inSeq);
  65
  66 /**
  67  * Returns the length of the character sequence.
  68  *
  69  * @param inSeq The input character sequence.
  70  * @param outLen The sequence length.
  71  * @return Any resultant error, if any.
  72  * @since 2024/06/27
  73  */
  74 typedef sjme_errorCode (*sjme_charSeq_lengthFunc)(
  75         sjme_attrInNotNull const sjme_charSeq* inSeq,
  76         sjme_attrOutNotNull sjme_jint* outLen);
  77
  78 /**
  79  * Functions which are used to process character sequences.
  80  *
  81  * @since 2024/06/26
  82  */
  83 typedef struct sjme_charSeq_functions
  84 {
  85         /** The character at the given index. */
  86         sjme_charSeq_charAtFunc charAt;
  87
  88         /** Deleting the sequence and freeing any resources. */
  89         sjme_charSeq_deleteFunc delete;
  90
  91         /** The length of the character sequence. */
  92         sjme_charSeq_lengthFunc length;
  93 } sjme_charSeq_functions;
  94
  95 struct sjme_charSeq
  96 {
  97         /** Front end data, if any. */
  98         sjme_frontEnd frontEnd;
  99
 100         /** Context pointer, if any. */
 101         sjme_pointer context;
 102
 103         /** The API for accessing the character sequence. */
 104         const sjme_charSeq_functions* impl;
 105 };
 106
 107 /**
 108  * Returns the character at the given index.
 109  *
 110  * @param inSeq The input character sequence.
 111  * @param inIndex The index to get from.
 112  * @param outChar The resultant character.
 113  * @return Any resultant error, if any.
 114  * @since 2024/06/27
 115  */
 116 sjme_errorCode sjme_charSeq_charAt(
 117         sjme_attrInNotNull const sjme_charSeq* inSeq,
 118         sjme_attrInPositive sjme_jint inIndex,
 119         sjme_attrOutNotNull sjme_jchar* outChar);
 120
 121 /**
 122  * Deletes the given static character sequence.
 123  *
 124  * @param inOutSeq The input/output sequence.
 125  * @return Any resultant error, if any.
 126  * @since 2024/06/26
 127  */
 128 sjme_errorCode sjme_charSeq_deleteStatic(
 129         sjme_attrInNotNull sjme_charSeq* inOutSeq);
 130
 131 /**
 132  * Returns the length of the character sequence.
 133  *
 134  * @param inSeq The input character sequence.
 135  * @param outLen The sequence length.
 136  * @return Any resultant error, if any.
 137  * @since 2024/06/27
 138  */
 139 sjme_errorCode sjme_charSeq_length(
 140         sjme_attrInNotNull const sjme_charSeq* inSeq,
 141         sjme_attrOutNotNull sjme_jint* outLen);
 142
 143 /**
 144  * Checks if the given character sequence equals the given character sequence.
 145  *
 146  * @param inSeq The sequence to check.
 147  * @param outResult The result of the check.
 148  * @param equalsSeq The char sequence to check for equality against.
 149  * @return Any resultant error, if any.
 150  * @since 2024/08/08
 151  */
 152 sjme_errorCode sjme_charSeq_equalsCharSeq(
 153         sjme_attrInNotNull const sjme_charSeq* inSeq,
 154         sjme_attrOutNotNull sjme_jboolean* outResult,
 155         sjme_attrInNotNull const sjme_charSeq* equalsSeq);
 156
 157 /**
 158  * Checks if the given character sequence equals the given UTF string.
 159  *
 160  * @param inSeq The sequence to check.
 161  * @param outResult The result of the check.
 162  * @param equalsUtf The UTF sequence to check for equality against.
 163  * @return Any resultant error, if any.
 164  * @since 2024/08/08
 165  */
 166 sjme_errorCode sjme_charSeq_equalsUtf(
 167         sjme_attrInNotNull const sjme_charSeq* inSeq,
 168         sjme_attrOutNotNull sjme_jboolean* outResult,
 169         sjme_attrInNotNull sjme_lpcstr equalsUtf);
 170
 171 /**
 172  * Checks if the given character sequence equals the given UTF string.
 173  *
 174  * @param inSeq The sequence to check.
 175  * @param equalsUtf The UTF sequence to check for equality against.
 176  * @return Returns whether it matches, note that if there is an error
 177  * then @c SJME_JNI_FALSE will be returned and the error will be hidden.
 178  * @since 2024/08/08
 179  */
 180 sjme_jboolean sjme_charSeq_equalsUtfR(
 181         sjme_attrInNotNull const sjme_charSeq* inSeq,
 182         sjme_attrInNotNull sjme_lpcstr equalsUtf);
 183
 184 /**
 185  * Initializes the given static character sequence.
 186  *
 187  * @param inOutSeq The input/output sequence.
 188  * @param inFunctions The input functions for the character sequence.
 189  * @param inOptContext The context to set.
 190  * @param inOptFrontEnd The front end data to copy.
 191  * @return Any resultant error, if any.
 192  * @since 2024/06/27
 193  */
 194 sjme_errorCode sjme_charSeq_newStatic(
 195         sjme_attrInNotNull sjme_charSeq* inOutSeq,
 196         sjme_attrInNotNull const sjme_charSeq_functions* inFunctions,
 197         sjme_attrInNullable sjme_pointer inOptContext,
 198         sjme_attrInNullable sjme_frontEnd* inOptFrontEnd);
 199
 200 /**
 201  * Creates a character sequence that accesses the given standard C string
 202  * as Utf characters.
 203  *
 204  * @param inOutSeq The resultant sequence.
 205  * @param inString The string to wrap.
 206  * @return Any resultant error, if any.
 207  * @since 2024/07/26
 208  */
 209 sjme_errorCode sjme_charSeq_newUtfStatic(
 210         sjme_attrInNotNull sjme_charSeq* inOutSeq,
 211         sjme_attrInNotNull sjme_lpcstr inString);
 212
 213 /**
 214  * Checks if the given character sequence starts with the given character
 215  * sequence.
 216  *
 217  * @param inSeq The sequence to check.
 218  * @param outResult The result of the check.
 219  * @param startsWithSeq The char sequence to check the start for.
 220  * @return Any resultant error, if any.
 221  * @since 2024/08/08
 222  */
 223 sjme_errorCode sjme_charSeq_startsWithCharSeq(
 224         sjme_attrInNotNull const sjme_charSeq* inSeq,
 225         sjme_attrOutNotNull sjme_jboolean* outResult,
 226         sjme_attrInNotNull const sjme_charSeq* startsWithSeq);
 227
 228 /**
 229  * Checks if the given character sequence starts with the given UTF string.
 230  *
 231  * @param inSeq The sequence to check.
 232  * @param outResult The result of the check.
 233  * @param startsWithSeq The UTF sequence to check the start for.
 234  * @return Any resultant error, if any.
 235  * @since 2024/08/08
 236  */
 237 sjme_errorCode sjme_charSeq_startsWithUtf(
 238         sjme_attrInNotNull const sjme_charSeq* inSeq,
 239         sjme_attrOutNotNull sjme_jboolean* outResult,
 240         sjme_attrInNotNull sjme_lpcstr startsWithUtf);
 241
 242 /**
 243  * Checks if the given character sequence starts with the given UTF string.
 244  *
 245  * @param inSeq The sequence to check.
 246  * @param startsWithUtf The UTF sequence to check the start for.
 247  * @return Returns whether it matches, note that if there is an error
 248  * then @c SJME_JNI_FALSE will be returned and the error will be hidden.
 249  * @since 2024/08/08
 250  */
 251 sjme_jboolean sjme_charSeq_startsWithUtfR(
 252         sjme_attrInNotNull const sjme_charSeq* inSeq,
 253         sjme_attrInNotNull sjme_lpcstr startsWithUtf);
 254
 255 /*--------------------------------------------------------------------------*/
 256
 257 /* Anti-C++. */
 258 #ifdef __cplusplus
 259         #ifdef SJME_CXX_SQUIRRELJME_CHARSEQ_H
 260 }
 261                 #undef SJME_CXX_SQUIRRELJME_CHARSEQ_H
 262                 #undef SJME_CXX_IS_EXTERNED
 263         #endif /* #ifdef SJME_CXX_SQUIRRELJME_CHARSEQ_H */
 264 #endif     /* #ifdef __cplusplus */
 265
 266 #endif /* SQUIRRELJME_CHARSEQ_H */