Special String Instance Pattern
[Patterns]

Objects Acting as Well-known String Values.

A Special String Instance is a type, or an instance of such a type, that acts as a string with a special value.

For example, the

The basic semantics of a special string instance can be achieved with conversion functions, as in the following:

std::string get_cwd()
{
  stlsoft::auto_buffer<char>  buff(1 + unixstl::filesystem_traits<char>::path_max());

  ::getcwd(&buff, buff.size());

  return std::string(buff.data(), buff.size());
}

However, it's harder to achieve the features that are available with a class-based approach:

Static (per-class) state, for values that do not change, such as the Windows directory.
Simple, succinct policies for specifying each Special String Instance type's behaviour.
Simple customisation of the allocator policy used.
Straightforward use of auto_buffer for optimised memory allocation.

Using stlsoft::special_string_instance_0 / stlsoft::special_string_instance_1, all that is required is a simple policy for each type. The following listing is the full definition of the winstl::cwd_policy, which is combined with stlsoft::special_string_instance_0 to define the winstl::current_directory_a, winstl::current_directory_w and winstl::current_directory types:

template <typename C>
struct cwd_policy
{
  typedef C                           char_type;
  typedef processheap_allocator<C>    allocator_type;
  typedef size_t                      size_type;
  typedef size_type                   (*pfn_type)(char_type *, size_type);

  enum { internalBufferSize       =   128 };
  enum { allowImplicitConversion  =   1   };
  enum { sharedState              =   0   };

  static pfn_type     get_fn()
  {
    return winstl::filesystem_traits<char_type>::get_current_directory;
  }
};

The following listing is the full definition of the winstl::sysdir_policy, which is combined with stlsoft::special_string_instance_0 to define the winstl::system_directory_a, winstl::system_directory_w and winstl::system_directory types. Note that the enumerator sharedState is 1, which means that the evaluated value of the Windows system directory will be shared between all instances of the class, since it is immutable for the lifetime of the process (and indeed of an installation).

template <typename C>
struct sysdir_policy
{
  typedef C                           char_type;
  typedef processheap_allocator<C>    allocator_type;
  typedef size_t                      size_type;
  typedef size_type                   (*pfn_type)(char_type *, size_type);

  enum { internalBufferSize       =   32  };
  enum { allowImplicitConversion  =   1   };
  enum { sharedState              =   1   };

  static pfn_type     get_fn()
  {
    return winstl::filesystem_traits<char_type>::get_system_directory;
  }
};

Special String Instance Pattern [Patterns]

Special String Instance Pattern
[Patterns]