src/strings_internal.h

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD 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.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /** @file strings_interal.h Types and functions related to the internal workings of formatting OpenTTD's strings. */
   9
  10 #ifndef STRINGS_INTERNAL_H
  11 #define STRINGS_INTERNAL_H
  12
  13 #include "strings_func.h"
  14 #include "string_func.h"
  15
  16 /** The data required to format and validate a single parameter of a string. */
  17 struct StringParameter {
  18         uint64_t data; ///< The data of the parameter.
  19         std::unique_ptr<std::string> string; ///< Copied string value, if it has any.
  20         char32_t type; ///< The #StringControlCode to interpret this data with when it's the first parameter, otherwise '\0'.
  21 };
  22
  23 class StringParameters {
  24 protected:
  25         StringParameters *parent = nullptr; ///< If not nullptr, this instance references data from this parent instance.
  26         std::span<StringParameter> parameters = {}; ///< Array with the actual parameters.
  27
  28         size_t offset = 0; ///< Current offset in the parameters span.
  29         char32_t next_type = 0; ///< The type of the next data that is retrieved.
  30
  31         StringParameters(std::span<StringParameter> parameters = {}) :
  32                 parameters(parameters)
  33         {}
  34
  35         StringParameter *GetNextParameterPointer();
  36
  37 public:
  38         /**
  39          * Create a new StringParameters instance that can reference part of the data of
  40          * the given parent instance.
  41          */
  42         StringParameters(StringParameters &parent, size_t size) :
  43                 parent(&parent),
  44                 parameters(parent.parameters.subspan(parent.offset, size))
  45         {}
  46
  47         void PrepareForNextRun();
  48         void SetTypeOfNextParameter(char32_t type) { this->next_type = type; }
  49
  50         /**
  51          * Get the current offset, so it can be backed up for certain processing
  52          * steps, or be used to offset the argument index within sub strings.
  53          * @return The current offset.
  54          */
  55         size_t GetOffset() { return this->offset; }
  56
  57         /**
  58          * Set the offset within the string from where to return the next result of
  59          * \c GetInt64 or \c GetInt32.
  60          * @param offset The offset.
  61          */
  62         void SetOffset(size_t offset)
  63         {
  64                 /*
  65                  * The offset must be fewer than the number of parameters when it is
  66                  * being set. Unless restoring a backup, then the original value is
  67                  * correct as well as long as the offset was not changed. In other
  68                  * words, when the offset was already at the end of the parameters and
  69                  * the string did not consume any parameters.
  70                  */
  71                 assert(offset < this->parameters.size() || this->offset == offset);
  72                 this->offset = offset;
  73         }
  74
  75         /**
  76          * Advance the offset within the string from where to return the next result of
  77          * \c GetInt64 or \c GetInt32.
  78          * @param advance The amount to advance the offset by.
  79          */
  80         void AdvanceOffset(size_t advance)
  81         {
  82                 this->offset += advance;
  83                 assert(this->offset <= this->parameters.size());
  84         }
  85
  86         /**
  87          * Get the next parameter from our parameters.
  88          * This updates the offset, so the next time this is called the next parameter
  89          * will be read.
  90          * @return The next parameter's value.
  91          */
  92         template <typename T>
  93         T GetNextParameter()
  94         {
  95                 auto ptr = GetNextParameterPointer();
  96                 return static_cast<T>(ptr->data);
  97         }
  98
  99         /**
 100          * Get the next string parameter from our parameters.
 101          * This updates the offset, so the next time this is called the next parameter
 102          * will be read.
 103          * @return The next parameter's value.
 104          */
 105         const char *GetNextParameterString()
 106         {
 107                 auto ptr = GetNextParameterPointer();
 108                 return ptr->string != nullptr ? ptr->string->c_str() : nullptr;
 109         }
 110
 111         /**
 112          * Get a new instance of StringParameters that is a "range" into the
 113          * remaining existing parameters. Upon destruction the offset in the parent
 114          * is not updated. However, calls to SetDParam do update the parameters.
 115          *
 116          * The returned StringParameters must not outlive this StringParameters.
 117          * @return A "range" of the string parameters.
 118          */
 119         StringParameters GetRemainingParameters() { return GetRemainingParameters(this->offset); }
 120
 121         /**
 122          * Get a new instance of StringParameters that is a "range" into the
 123          * remaining existing parameters from the given offset. Upon destruction the
 124          * offset in the parent is not updated. However, calls to SetDParam do
 125          * update the parameters.
 126          *
 127          * The returned StringParameters must not outlive this StringParameters.
 128          * @param offset The offset to get the remaining parameters for.
 129          * @return A "range" of the string parameters.
 130          */
 131         StringParameters GetRemainingParameters(size_t offset)
 132         {
 133                 return StringParameters(this->parameters.subspan(offset, this->parameters.size() - offset));
 134         }
 135
 136         /** Return the amount of elements which can still be read. */
 137         size_t GetDataLeft() const
 138         {
 139                 return this->parameters.size() - this->offset;
 140         }
 141
 142         /** Get the type of a specific element. */
 143         char32_t GetTypeAtOffset(size_t offset) const
 144         {
 145                 assert(offset < this->parameters.size());
 146                 return this->parameters[offset].type;
 147         }
 148
 149         void SetParam(size_t n, uint64_t v)
 150         {
 151                 assert(n < this->parameters.size());
 152                 this->parameters[n].data = v;
 153                 this->parameters[n].string.reset();
 154         }
 155
 156         template <typename T, std::enable_if_t<std::is_base_of<StrongTypedefBase, T>::value, int> = 0>
 157         void SetParam(size_t n, T v)
 158         {
 159                 SetParam(n, v.base());
 160         }
 161
 162         void SetParam(size_t n, const char *str)
 163         {
 164                 assert(n < this->parameters.size());
 165                 this->parameters[n].data = 0;
 166                 this->parameters[n].string = std::make_unique<std::string>(str);
 167         }
 168
 169         void SetParam(size_t n, const std::string &str) { this->SetParam(n, str.c_str()); }
 170
 171         void SetParam(size_t n, std::string &&str)
 172         {
 173                 assert(n < this->parameters.size());
 174                 this->parameters[n].data = 0;
 175                 this->parameters[n].string = std::make_unique<std::string>(std::move(str));
 176         }
 177
 178         uint64_t GetParam(size_t n) const
 179         {
 180                 assert(n < this->parameters.size());
 181                 assert(this->parameters[n].string == nullptr);
 182                 return this->parameters[n].data;
 183         }
 184
 185         /**
 186          * Get the stored string of the parameter, or \c nullptr when there is none.
 187          * @param n The index into the parameters.
 188          * @return The stored string.
 189          */
 190         const char *GetParamStr(size_t n) const
 191         {
 192                 assert(n < this->parameters.size());
 193                 auto &param = this->parameters[n];
 194                 return param.string != nullptr ? param.string->c_str() : nullptr;
 195         }
 196 };
 197
 198 /**
 199  * Extension of StringParameters with its own statically sized buffer for
 200  * the parameters.
 201  */
 202 template <size_t N>
 203 class ArrayStringParameters : public StringParameters {
 204         std::array<StringParameter, N> params{}; ///< The actual parameters
 205
 206 public:
 207         ArrayStringParameters()
 208         {
 209                 this->parameters = std::span(params.data(), params.size());
 210         }
 211
 212         ArrayStringParameters(ArrayStringParameters&& other) noexcept
 213         {
 214                 *this = std::move(other);
 215         }
 216
 217         ArrayStringParameters& operator=(ArrayStringParameters &&other) noexcept
 218         {
 219                 this->offset = other.offset;
 220                 this->next_type = other.next_type;
 221                 this->params = std::move(other.params);
 222                 this->parameters = std::span(params.data(), params.size());
 223                 return *this;
 224         }
 225
 226         ArrayStringParameters(const ArrayStringParameters &other) = delete;
 227         ArrayStringParameters& operator=(const ArrayStringParameters &other) = delete;
 228 };
 229
 230 /**
 231  * Helper to create the StringParameters with its own buffer with the given
 232  * parameter values.
 233  * @param args The parameters to set for the to be created StringParameters.
 234  * @return The constructed StringParameters.
 235  */
 236 template <typename... Args>
 237 static auto MakeParameters(const Args&... args)
 238 {
 239         ArrayStringParameters<sizeof...(args)> parameters;
 240         size_t index = 0;
 241         (parameters.SetParam(index++, std::forward<const Args&>(args)), ...);
 242         return parameters;
 243 }
 244
 245 /**
 246  * Equivalent to the std::back_insert_iterator in function, with some
 247  * convenience helpers for string concatenation.
 248  */
 249 class StringBuilder {
 250         std::string *string;
 251
 252 public:
 253         /* Required type for this to be an output_iterator; mimics std::back_insert_iterator. */
 254         using value_type = void;
 255         using difference_type = void;
 256         using iterator_category = std::output_iterator_tag;
 257         using pointer = void;
 258         using reference = void;
 259
 260         /**
 261          * Create the builder of an external buffer.
 262          * @param start The start location to write to.
 263          * @param last  The last location to write to.
 264          */
 265         StringBuilder(std::string &string) : string(&string) {}
 266
 267         /* Required operators for this to be an output_iterator; mimics std::back_insert_iterator, which has no-ops. */
 268         StringBuilder &operator++() { return *this; }
 269         StringBuilder operator++(int) { return *this; }
 270         StringBuilder &operator*() { return *this; }
 271
 272         /**
 273          * Operator to add a character to the end of the buffer. Like the back
 274          * insert iterators this also increases the position of the end of the
 275          * buffer.
 276          * @param value The character to add.
 277          * @return Reference to this inserter.
 278          */
 279         StringBuilder &operator=(const char value)
 280         {
 281                 return this->operator+=(value);
 282         }
 283
 284         /**
 285          * Operator to add a character to the end of the buffer.
 286          * @param value The character to add.
 287          * @return Reference to this inserter.
 288          */
 289         StringBuilder &operator+=(const char value)
 290         {
 291                 this->string->push_back(value);
 292                 return *this;
 293         }
 294
 295         /**
 296          * Operator to append the given string to the output buffer.
 297          * @param str The string to add.
 298          * @return Reference to this inserter.
 299          */
 300         StringBuilder &operator+=(std::string_view str)
 301         {
 302                 *this->string += str;
 303                 return *this;
 304         }
 305
 306         /**
 307          * Encode the given Utf8 character into the output buffer.
 308          * @param c The character to encode.
 309          */
 310         void Utf8Encode(char32_t c)
 311         {
 312                 auto iterator = std::back_inserter(*this->string);
 313                 ::Utf8Encode(iterator, c);
 314         }
 315
 316         /**
 317          * Remove the given amount of characters from the back of the string.
 318          * @param amount The amount of characters to remove.
 319          * @return true iff there was enough space and the character got added.
 320          */
 321         void RemoveElementsFromBack(size_t amount)
 322         {
 323                 this->string->erase(this->string->size() - std::min(amount, this->string->size()));
 324         }
 325
 326         /**
 327          * Get the current index in the string.
 328          * @return The index.
 329          */
 330         size_t CurrentIndex()
 331         {
 332                 return this->string->size();
 333         }
 334
 335         /**
 336          * Get the reference to the character at the given index.
 337          * @return The reference to the character.
 338          */
 339         char &operator[](size_t index)
 340         {
 341                 return (*this->string)[index];
 342         }
 343 };
 344
 345 void GetStringWithArgs(StringBuilder &builder, StringID string, StringParameters &args, uint case_index = 0, bool game_script = false);
 346 std::string GetStringWithArgs(StringID string, StringParameters &args);
 347
 348 /* Do not leak the StringBuilder to everywhere. */
 349 void GenerateTownNameString(StringBuilder &builder, size_t lang, uint32_t seed);
 350 void GetTownName(StringBuilder &builder, const struct Town *t);
 351 void GRFTownNameGenerate(StringBuilder &builder, uint32_t grfid, uint16_t gen, uint32_t seed);
 352
 353 uint RemapNewGRFStringControlCode(uint scc, const char **str, StringParameters &parameters, bool modify_parameters);
 354
 355 #endif /* STRINGS_INTERNAL_H */