Method AssignString

source/var.cpp:504–730

ResultType Var::AssignString(LPCTSTR aBuf, VarSizeType aLength, bool aExactSize)
// Returns OK or FAIL.
// If aBuf isn't NULL, caller must ensure that aLength is either VARSIZE_MAX (which tells us that the
// entire strlen() of aBuf should be used) or an explicit length (can be zero) that the caller must
// ensure is less than or equal to the total length of aBuf (if less, only a substring is copied).
// If aBuf is NULL, the variable will be set up to handle a string of at least aLength
// in length.  In addition, if the var is the clipboard, it will be prepared for writing.
// Any existing contents of this variable will be destroyed regardless of whether aBuf is NULL.
// Note that aBuf's memory can safely overlap with that of this->Contents() because in that case the
// new length of the contents will always be less than or equal to the old length, and thus no
// reallocation/expansion is needed (such an expansion would free the source before it could be
// written to the destination).  This is because callers pass in an aBuf that is either:
// 1) Between this->Contents() and its terminator.
// 2) Equal to this->Contents() but with aLength passed in as shorter than this->Length().
//
// Caller can omit both params to set a var to be empty-string, but in that case, if the variable
// is of large capacity, its memory will not be freed.  This is by design because it allows the
// caller to exploit its knowledge of whether the var's large capacity is likely to be needed
// again in the near future, thus reducing the expected amount of memory fragmentation.
// To explicitly free the memory, use Assign("").
{
	if (mType == VAR_ALIAS)
		// For maintainability, it seems best not to use the following method:
		//    Var &var = *(mType == VAR_ALIAS ? mAliasFor : this);
		// If that were done, bugs would be easy to introduce in a long function like this one
		// if your forget at use the implicit "this" by accident.  So instead, just call self.
		return mAliasFor->AssignString(aBuf, aLength, aExactSize);

	bool do_assign = true;        // Set defaults.
	bool free_it_if_large = true; //
	if (!aBuf)
		if (aLength == VARSIZE_MAX) // Caller omitted this param too, so it wants to assign empty string.
		{
			free_it_if_large = false;
			aLength = 0; // aBuf is set to "" further below.
		}
		else // Caller gave a NULL buffer to signal us to ensure the var is at least aLength in capacity.
			do_assign = false;
	else // Caller provided a non-NULL buffer.
		if (aLength == VARSIZE_MAX) // Caller wants us to determine its length.
			aLength = (mCharContents == aBuf) ? _CharLength() : (VarSizeType)_tcslen(aBuf); // v1.0.45: Added optimization check: (mContents == aBuf).  v1.1.09.03: Replaced CharLength() with _CharLength() to avoid updating contents (probably only applicable when aBuf == Var::sEmptyString).
		//else leave aLength as the caller-specified value in case it's explicitly shorter than the apparent length.
	if (!aBuf)
		aBuf = _T("");  // From here on, make sure it's the empty string for all uses (read-only empty string vs. sEmptyString seems more appropriate in this case).

	size_t space_needed = aLength + 1; // +1 for the zero terminator.
	size_t space_needed_in_bytes = space_needed * sizeof(TCHAR);

	if (mType == VAR_VIRTUAL)
	{
		if (do_assign)
			return AssignVirtual(ExprTokenType(const_cast<LPTSTR>(aBuf), aLength));
		// Since above didn't return, the caller wants to allocate some temporary memory for
		// writing the value into, and should call Close() in order to commit the actual value.
	}
	else if (mType == VAR_CONSTANT) // Might be impossible due to prior validation of assignments/output vars.
		return g_script.VarIsReadOnlyError(this);