Make Fl_String and Fl_Int_Vector private (#789)

- add CMake option 'OPTION_USE_STD'
- add configure option '--enable-use_std'
- move FL/Fl_String.H to src/Fl_String.H
- move FL/Fl_Int_Vector.H to src/Fl_Int_Vector.H
- remove Fl_String from demo program examples/callbacks.cxx
- remove Fl_Int_Vector from public header FL/Fl_Table.H
- some methods of Fl_Table are no longer inline
- add CMake option OPTION_USE_STD to allow std::string in some
  selected functions and methods

Experimental, may be removed before release:

- use either Fl_Int_Vector or std::vector in Fl_Table depending
  on CMake OPTION_USE_STD or configure --enable-use_std

Move all fl_filename* functions that use Fl_String to fluid

Main changes in fluid:
 - add fluid_filename.h and .cxx
 - include "fluid_filename.h" rather than <FL/filename.H>

Update fl_input(), fl_password() and test/ask

- add maxchar parameter to fl_input() and fl_password()
- fl_input_str() and fl_password_str() are optional and return
  std::string if enabled (FLTK_USE_STD)

6 files changed, 95 insertions, 344 deletions

diff --git a/FL/Fl_Int_Vector.H b/FL/Fl_Int_Vector.H
deleted file mode 100644
index d21e8668c..000000000
--- a/FL/Fl_Int_Vector.H
+++ /dev/null
@@ -1,166 +0,0 @@
-//
-// An STL-ish vector without templates for the Fast Light Tool Kit (FLTK).
-//
-// Copyright 2002 by Greg Ercolano.
-// Copyright 2022-2023 by Bill Spitzak and others.
-//
-// This library is free software. Distribution and use rights are outlined in
-// the file "COPYING" which should have been included with this file.  If this
-// file is missing or damaged, see the license at:
-//
-//     https://www.fltk.org/COPYING.php
-//
-// Please see the following page on how to report bugs and issues:
-//
-//     https://www.fltk.org/bugs.php
-//
-
-#ifndef Fl_Int_Vector_H
-#define Fl_Int_Vector_H
-
-#include <FL/Fl_Export.H>
-
-/** \file FL/Fl_Int_Vector.H
-  An STL-ish vector implemented without templates.
-*/
-
-/**
-  An STL-ish vector without templates.
-
-  Handles dynamic memory management of an integer array, and allows
-  array elements to be accessed with zero based indexing: v[0], v[1]..
-
-  Common use:
-  \code
-  #include <stdio.h>
-  #include <FL/Fl_Int_Vector.H>
-  int main() {
-      Fl_Int_Vector v;
-
-      // Create an array of values 11,22,33:
-      v.push_back(11);   // add first element
-      v.push_back(22);   // add second element
-      v.push_back(33);   // add third element
-
-      // Assignment by subscript
-      v[1] = 222;        // changes 2nd element from 22 to 222
-
-      // Loop through printing the values
-      for ( unsigned int i=0; i<v.size(); i++ )
-          printf("%d ", v[i]);  // access the elements
-      printf("\n");
-
-      // Clear the array
-      v.size(0);
-  }
-  \endcode
-
-  \todo
-      - Add other std::vector methods like erase(), etc.
-      - Make memory blocking size flexible, and add related methods like capacity(), reserve(), shrink_to_fit(), etc.
-      - Add non-std methods that are nevertheless needed, e.g. insert(index,val), delete(index), delete(start, end), swap(a_idx,b_idx)
-*/
-class FL_EXPORT Fl_Int_Vector {
-  int *arr_;
-  unsigned int size_;
-
-  /**
-    Initialize internals.
-    Private: For use internally by the class's ctors only.
-  */
-  void init() {
-    arr_ = 0;
-    size_ = 0;
-  }
-  void copy(int *newarr, unsigned int newsize);
-
-public:
-  /** Create an empty vector of integers. */
-  Fl_Int_Vector() {
-    init();
-  }
-
-  ~Fl_Int_Vector();
-
-  /** Copy constructor. */
-  Fl_Int_Vector(Fl_Int_Vector &o) {
-    init();
-    copy(o.arr_, o.size_);
-  }
-
-  /**
-    Assignment operator. Similar to the copy constructor,
-    creates a separate copy of the source array, freeing any
-    previous contents in the current integer array.
-  */
-  Fl_Int_Vector &operator=(Fl_Int_Vector &o) {
-    init();
-    copy(o.arr_, o.size_);
-    return *this;
-  }
-
-  /**
-    Access the specified integer element at index position \p x.
-    \warning No range checking is done on \p x, which must be less than size().
-  */
-  int operator[](int x) const {
-    return arr_[x];
-  }
-
-  /**
-    Access the specified integer element at index position \p x as a reference.
-
-    This allows assignment by index through the returned reference, e.g. arr[1] = 222;
-    where arr[1] ends up being a reference to ptr[1], and then 222 is assigned to that ref.
-
-    \warning No range checking is done on \p x, which must be less than size().
-  */
-  int &operator[](int x) {
-    return arr_[x];
-  }
-
-  /** Return the number of integer elements in the array. */
-  unsigned int size() const {
-    return size_;
-  }
-
-  void size(unsigned int count);
-
-  /**
-    Removes the last element the last element and returns its value.
-
-    \warning You must not call pop_back() if the array is empty, i.e. if (size() == 0).
-    \todo Internals should maybe assert(size_ != 0)
-  */
-  int pop_back() {
-    int tmp = arr_[size_ - 1];
-    size_--;
-    return tmp;
-  }
-
-  /** Appends \p val to the array, enlarging the array by one. */
-  void push_back(int val) {
-    unsigned int x = size_;
-    size(size_ + 1);
-    arr_[x] = val;
-  }
-
-  /**
-    Return the last element in the array.
-    \warning You must not call back() if the array is empty, i.e. if (size() == 0).
-    \todo Internals should maybe assert(size_ != 0)
-  */
-  int back() const {
-    return arr_[size_ - 1];
-  }
-
-  /**
-    Checks if array has no elements.
-    Same as a test for (size() == 0).
-  */
-  bool empty() const {
-    return (size_ == 0) ? true : false;
-  }
-};
-
-#endif // Fl_Int_Vector_H
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index adf976706..98cc42523 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -25,6 +25,9 @@
 #  include "fl_attr.h"
 
 //class Fl_String;
+#if (FLTK_USE_STD)
+#include <string>
+#endif
 
 /**
  \brief Fl_Preferences store user settings between application starts.
@@ -241,7 +244,6 @@ public:
   char set( const char *entry, double value, int precision );
   char set( const char *entry, const char *value );
   char set( const char *entry, const void *value, int size );
-//  char set( const char *entry, const Fl_String &value );
 
   char get( const char *entry, int &value, int defaultValue );
   char get( const char *entry, float &value,  float defaultValue );
@@ -251,8 +253,15 @@ public:
   char get( const char *entry, void *&value,  const void *defaultValue, int defaultSize );
   char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int maxSize );
   char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int *size );
+
+//  char set( const char *entry, const Fl_String &value );
 //  char get( const char *entry, Fl_String &value, const Fl_String &defaultValue );
 
+#if (FLTK_USE_STD)
+  char set( const char *entry, const std::string &value );
+  char get( const char *entry, std::string &value, const std::string &defaultValue );
+#endif
+
   int size( const char *entry );
 
   char get_userdata_path( char *path, int pathlen );
diff --git a/FL/Fl_String.H b/FL/Fl_String.H
deleted file mode 100644
index f8e273d65..000000000
--- a/FL/Fl_String.H
+++ /dev/null
@@ -1,133 +0,0 @@
-//
-// Basic Fl_String header for the Fast Light Tool Kit (FLTK).
-//
-// Copyright 2021-2023 by Bill Spitzak and others.
-//
-// This library is free software. Distribution and use rights are outlined in
-// the file "COPYING" which should have been included with this file.  If this
-// file is missing or damaged, see the license at:
-//
-//     https://www.fltk.org/COPYING.php
-//
-// Please see the following page on how to report bugs and issues:
-//
-//     https://www.fltk.org/bugs.php
-//
-
-#ifndef _FL_Fl_String_H_
-#define _FL_Fl_String_H_
-
-/** \file FL/Fl_String.H
-  Basic Fl_String class for FLTK.
-*/
-
-#include "Fl_Export.H"
-
-// See: https://en.cppreference.com/w/cpp/string/basic_string/basic_string
-
-/**
-  Fl_String is the basic string class for FLTK.
-
-  In this version Fl_String can be used to store strings, copy strings,
-  move strings, and do basic string manipulation. Fl_String implements a
-  subset of std::string with a couple of extensions. std::string should be
-  a drop-in if we ever decide to allow templates and the std library.
-
-  Fl_String always maintains a trailing \e nul byte, but can also contain
-  \e nul bytes inside the string if the constructor
-  Fl_String(const char *str, int size) is used.
-
-  Assignment and copy constructors \b copy the string value such that the
-  source string can be freed immediately after the assignment.
-
-  c_str() and data() can be an empty string \c "", but never be \c NULL.
-
-  The method size() returns the full string size, whether the string contains
-  embedded \c nul bytes or not. The special method Fl_String::strlen() returns
-  the length of the string up to the first \e nul.
-
-  All methods of Fl_String work on a byte level. They are not UTF-8 aware,
-  but may hold and manipulate UTF-8 strings if done with care.
-
-  \since 1.4.0
-*/
-class FL_EXPORT Fl_String {
-
-private:
-  /*
-   FLTK does no small string optimization.
-   If the string is empty and capacity is not set, buffer_ will be NULL.
-   */
-  char *buffer_;
-  int size_;
-  int capacity_;
-
-  void init_();
-  void grow_(int n);
-  void shrink_(int n);
-  Fl_String &replace_(int at, int n_del, const char *src, int n_ins);
-
-protected:
-  static const char NUL;
-
-public:
-  static const int npos;
-
-  // ---- Assignment
-  Fl_String();
-  Fl_String(const Fl_String &str);
-  Fl_String(const char *cstr);
-  Fl_String(const char *str, int size);
-  ~Fl_String();
-  Fl_String& operator=(const Fl_String &str);
-  Fl_String& operator=(const char *cstr);
-  Fl_String &assign(const Fl_String &str);
-  Fl_String &assign(const char *cstr);
-  Fl_String &assign(const char *str, int size);
-
-  // ---- Element Access
-  char at(int pos) const;
-  char operator[](int n) const;
-  char &operator[](int n);
-  const char *data() const;
-  char *data();
-  const char *c_str() const;
-
-  // ---- Capacity
-  bool empty() const;
-  int size() const;
-  void reserve(int n);
-  int capacity() const;
-  void shrink_to_fit();
-
-  // --- Operations
-  void clear();
-  Fl_String &insert(int at, const char *src, int n_ins=npos);
-  Fl_String &insert(int at, const Fl_String &src);
-  Fl_String &erase(int at, int n_del);
-  void push_back(char c);
-  void pop_back();
-  Fl_String &append(const char *src, int n_ins=npos);
-  Fl_String &append(const Fl_String &src);
-  Fl_String &append(char c);
-  Fl_String &operator+=(const char *src);
-  Fl_String &operator+=(const Fl_String &src);
-  Fl_String &operator+=(char c);
-  int find(const Fl_String &needle, int start_pos=0) const;
-  Fl_String &replace(int at, int n_del, const char *src, int n_ins=npos);
-  Fl_String &replace(int at, int n_del, const Fl_String &src);
-  Fl_String substr(int pos=0, int n=npos) const;
-  void resize(int n);
-
-  // --- Non Standard
-  int strlen() const;
-  void debug(const char *info = 0) const;
-  void hexdump(const char *info = 0) const;
-}; // class Fl_String
-
-// ---- Non-member functions
-FL_EXPORT Fl_String operator+(const Fl_String& lhs, const Fl_String& rhs);
-FL_EXPORT Fl_String operator+(const Fl_String& lhs, const char* rhs);
-FL_EXPORT bool operator==(const Fl_String & lhs, const Fl_String & rhs);
-
-#endif // _FL_Fl_String_H_
diff --git a/FL/Fl_Table.H b/FL/Fl_Table.H
index 9f31fa020..1adc29255 100644
--- a/FL/Fl_Table.H
+++ b/FL/Fl_Table.H
@@ -3,6 +3,7 @@
 //
 // Copyright 2002 by Greg Ercolano.
 // Copyright (c) 2004 O'ksi'D
+// Copyright 2023 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -20,7 +21,18 @@
 
 #include <FL/Fl_Group.H>
 #include <FL/Fl_Scroll.H>
-#include <FL/Fl_Int_Vector.H>
+
+// EXPERIMENTAL
+// We use either std::vector or the private class Fl_Int_Vector
+// depending on the build option OPTION_USE_STD or --enable-use_std.
+// This option allows to use std::string and std::vector in FLTK 1.4.x
+
+#if (FLTK_USE_STD)
+#include <vector>
+typedef std::vector<int> Fl_Int_Vector;
+#else
+class Fl_Int_Vector; // private class declared in src/Fl_Int_Vector.H
+#endif
 
 /**
   A table of widgets or other content.
@@ -155,8 +167,12 @@ private:
   };
   unsigned int flags_;
 
-  Fl_Int_Vector _colwidths;             // column widths in pixels
-  Fl_Int_Vector _rowheights;            // row heights in pixels
+  Fl_Int_Vector *_colwidths;            // column widths in pixels
+  Fl_Int_Vector *_rowheights;           // row heights in pixels
+
+  // number of columns and rows == size of corresponding vectors
+  int col_size();                       // size of the column widths vector
+  int row_size();                       // size of the row heights vector
 
   Fl_Cursor _last_cursor;               // last mouse cursor before changed to 'resize' cursor
 
@@ -433,7 +449,7 @@ public:
     return(table->box());
   }
 
-  virtual void rows(int val);                   // set/get number of rows
+  virtual void rows(int val);                   // set number of rows
 
   /**
    Returns the number of rows in the table.
@@ -442,7 +458,7 @@ public:
     return(_rows);
   }
 
-  virtual void cols(int val);                   // set/get number of columns
+  virtual void cols(int val);                   // set number of columns
 
   /**
    Get the number of columns in the table.
@@ -656,23 +672,15 @@ public:
     return(_col_header_color);
   }
 
-  void row_height(int row, int height);         // set/get row height
+  void row_height(int row, int height);         // set row height in pixels
 
-  /**
-    Returns the current height of the specified row as a value in pixels.
-  */
-  inline int row_height(int row) {
-    return((row<0 || row>=(int)_rowheights.size()) ? 0 : _rowheights[row]);
-  }
+  // Returns the current height of the specified row as a value in pixels.
+  int row_height(int row);
 
-  void col_width(int col, int width);           // set/get a column's width
+  void col_width(int col, int width);           // set a column's width in pixels
 
-  /**
-    Returns the current width of the specified column in pixels.
-  */
-  inline int col_width(int col) {
-    return((col<0 || col>=(int)_colwidths.size()) ? 0 : _colwidths[col]);
-  }
+  // Returns the current width of the specified column in pixels.
+  int col_width(int col);
 
   /**
     Convenience method to set the height of all rows to the
diff --git a/FL/filename.H b/FL/filename.H
index b5b76f92f..92bf96f73 100644
--- a/FL/filename.H
+++ b/FL/filename.H
@@ -1,7 +1,7 @@
 /*
  * Filename header file for the Fast Light Tool Kit (FLTK).
  *
- * Copyright 1998-2018 by Bill Spitzak and others.
+ * Copyright 1998-2023 by Bill Spitzak and others.
  *
  * This library is free software. Distribution and use rights are outlined in
  * the file "COPYING" which should have been included with this file.  If this
@@ -14,16 +14,30 @@
  *     https://www.fltk.org/bugs.php
  */
 
-/** \file
- File names and URI utility functions.
+/*
+ * Note to devs:
+ * Under Windows, we include filename.H from numericsort.c; this should probably change.
+ * This implies that we need C-style comments and '#ifdef __cplusplus ... #endif'
  */
 
+/** \file
+  File names and URI utility functions.
+*/
+
 #ifndef FL_FILENAME_H
 #  define FL_FILENAME_H
 
 #include "Fl_Export.H"
 #include <FL/platform_types.h>
 
+#ifdef __cplusplus
+
+// The following include is not (yet) used in FLTK 1.4
+// In FLTK 1.5 or 4.0 using std::string would be default.
+// #include <string>
+
+#endif /* __cplusplus */
+
 /** \addtogroup filenames File names and URI utility functions
  File names and URI functions defined in <FL/filename.H>
     @{ */
@@ -55,22 +69,25 @@ FL_EXPORT int fl_filename_isdir(const char *name);
 
 #  if defined(__cplusplus)
 
-class Fl_String;
-
-FL_EXPORT Fl_String fl_filename_name(const Fl_String &filename);
-FL_EXPORT Fl_String fl_filename_path(const Fl_String &filename);
-FL_EXPORT Fl_String fl_filename_ext(const Fl_String &filename);
-FL_EXPORT Fl_String fl_filename_setext(const Fl_String &filename, const Fl_String &new_extension);
-FL_EXPORT Fl_String fl_filename_expand(const Fl_String &from);
 FL_EXPORT int fl_filename_absolute(char *to, int tolen, const char *from, const char *cwd);
-FL_EXPORT Fl_String fl_filename_absolute(const Fl_String &from);
-FL_EXPORT Fl_String fl_filename_absolute(const Fl_String &from, const Fl_String &base);
 FL_EXPORT int fl_filename_relative(char *to, int tolen, const char *from, const char *cwd);
-FL_EXPORT Fl_String fl_filename_relative(const Fl_String &from);
-FL_EXPORT Fl_String fl_filename_relative(const Fl_String &from, const Fl_String &base);
-FL_EXPORT Fl_String fl_getcwd();
 
-#  endif
+
+// FIXME: We can't do this in 1.4.x - enable this block in 1.5 or higher.
+// See fluid/fluid_filename.{h|cxx} for an implementation using Fl_String.
+
+// FL_EXPORT std::string fl_filename_name(const std::string &filename);
+// FL_EXPORT std::string fl_filename_path(const std::string &filename);
+// FL_EXPORT std::string fl_filename_ext(const std::string &filename);
+// FL_EXPORT std::string fl_filename_setext(const std::string &filename, const std::string &new_extension);
+// FL_EXPORT std::string fl_filename_expand(const std::string &from);
+// FL_EXPORT std::string fl_filename_absolute(const std::string &from);
+// FL_EXPORT std::string fl_filename_absolute(const std::string &from, const std::string &base);
+// FL_EXPORT std::string fl_filename_relative(const std::string &from);
+// FL_EXPORT std::string fl_filename_relative(const std::string &from, const std::string &base);
+// FL_EXPORT std::string fl_getcwd();
+
+#  endif /* defined(__cplusplus) */
 
 #  if defined(__cplusplus) && !defined(FL_DOXYGEN)
 /*
@@ -120,7 +137,7 @@ FL_EXPORT void fl_decode_uri(char *uri);
 #  endif /* __cplusplus */
 
 /*
- * FLTK 1.0.x compatibility definitions (FLTK_1_0_COMPAT) dropped in 1.4.0
+ * Note: FLTK 1.0.x compatibility definitions (FLTK_1_0_COMPAT) dropped in 1.4.0
  */
 
 #endif /* FL_FILENAME_H */
diff --git a/FL/fl_ask.H b/FL/fl_ask.H
index c4eb3ab86..2387a1947 100644
--- a/FL/fl_ask.H
+++ b/FL/fl_ask.H
@@ -22,9 +22,12 @@
 #define _FL_fl_ask_H_
 
 #include <FL/Enumerations.H>
-#include <FL/Fl_String.H>
 #include <FL/fl_attr.h>
 
+#if (FLTK_USE_STD)
+#include <string>
+#endif
+
 class Fl_Widget;
 
 /** Defines the different system beeps available.
@@ -65,22 +68,35 @@ FL_EXPORT const char *fl_password(const char *label, const char *deflt = 0, ...)
 FL_EXPORT int fl_choice_n(const char *q, const char *b0, const char *b1, const char *b2, ...)
     __fl_attr((__format__(__printf__, 1, 5)));
 
-// since FLTK 1.4.0:
-// - fl_input_str()    with limited input size
-// - fl_password_str() with limited input size (*_str)
+// since FLTK 1.4.0: with 'maxchar' to limit input size
+
+FL_EXPORT const char *fl_input(int maxchar, const char *label, const char *deflt = 0, ...)
+    __fl_attr((__format__(__printf__, 2, 4)));
 
-FL_EXPORT Fl_String fl_input_str(int maxchar, const char *label, const char *deflt = 0, ...)
+FL_EXPORT const char *fl_password(int maxchar, const char *label, const char *deflt = 0, ...)
     __fl_attr((__format__(__printf__, 2, 4)));
 
-FL_EXPORT Fl_String fl_input_str(int &ret, int maxchar, const char *label, const char *deflt = 0, ...)
+// since FLTK 1.4.0 -- only with option FLTK_USE_STD
+
+// - fl_input_str()    with limited input size, returns std::string
+// - fl_password_str() with limited input size, returns std::string
+
+#if (FLTK_USE_STD)
+
+FL_EXPORT std::string fl_input_str(int maxchar, const char *label, const char *deflt = 0, ...)
+    __fl_attr((__format__(__printf__, 2, 4)));
+
+FL_EXPORT std::string fl_input_str(int &ret, int maxchar, const char *label, const char *deflt = 0, ...)
     __fl_attr((__format__(__printf__, 3, 5)));
 
-FL_EXPORT Fl_String fl_password_str(int maxchar, const char *label, const char *deflt = 0, ...)
+FL_EXPORT std::string fl_password_str(int maxchar, const char *label, const char *deflt = 0, ...)
     __fl_attr((__format__(__printf__, 2, 4)));
 
-FL_EXPORT Fl_String fl_password_str(int &ret, int maxchar, const char *label, const char *deflt = 0, ...)
+FL_EXPORT std::string fl_password_str(int &ret, int maxchar, const char *label, const char *deflt = 0, ...)
     __fl_attr((__format__(__printf__, 3, 5)));
 
+#endif
+
 FL_EXPORT Fl_Widget *fl_message_icon();
 extern FL_EXPORT Fl_Font fl_message_font_;
 extern FL_EXPORT Fl_Fontsize fl_message_size_;