initialise
[debian/goprotobuf.git] / proto / lib.go
1 // Go support for Protocol Buffers - Google's data interchange format
2 //
3 // Copyright 2010 Google Inc.  All rights reserved.
4 // http://code.google.com/p/goprotobuf/
5 //
6 // Redistribution and use in source and binary forms, with or without
7 // modification, are permitted provided that the following conditions are
8 // met:
9 //
10 //     * Redistributions of source code must retain the above copyright
11 // notice, this list of conditions and the following disclaimer.
12 //     * Redistributions in binary form must reproduce the above
13 // copyright notice, this list of conditions and the following disclaimer
14 // in the documentation and/or other materials provided with the
15 // distribution.
16 //     * Neither the name of Google Inc. nor the names of its
17 // contributors may be used to endorse or promote products derived from
18 // this software without specific prior written permission.
19 //
20 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
32 /*
33         The proto package converts data structures to and from the
34         wire format of protocol buffers.  It works in concert with the
35         Go source code generated for .proto files by the protocol compiler.
36
37         A summary of the properties of the protocol buffer interface
38         for a protocol buffer variable v:
39
40           - Names are turned from camel_case to CamelCase for export.
41           - There are no methods on v to set and get fields; just treat
42                 them as structure fields.
43           - The zero value for a struct is its correct initialization state.
44                 All desired fields must be set before marshaling.
45           - A Reset() method will restore a protobuf struct to its zero state.
46           - Non-repeated fields are pointers to the values; nil means unset.
47                 That is, optional or required field int32 f becomes F *int32.
48           - Repeated fields are slices.
49           - Helper functions are available to simplify the getting and setting of fields:
50                 foo.String = proto.String("hello") // set field
51                 s := proto.GetString(foo.String)  // get field
52           - Constants are defined to hold the default values of all fields that
53                 have them.  They have the form Default_StructName_FieldName.
54           - Enums are given type names and maps between names to values,
55                 plus a helper function to create values.  Enum values are prefixed
56                 with the enum's type name. Enum types have a String method.
57           - Nested groups and enums have type names prefixed with the name of
58                 the surrounding message type.
59           - Extensions are given descriptor names that start with E_,
60                 followed by an underscore-delimited list of the nested messages
61                 that contain it (if any) followed by the CamelCased name of the
62                 extension field itself.  HasExtension, ClearExtension, GetExtension
63                 and SetExtension are functions for manipulating extensions.
64           - Marshal and Unmarshal are functions to encode and decode the wire format.
65
66         The simplest way to describe this is to see an example.
67         Given file test.proto, containing
68
69                 package example;
70
71                 enum FOO { X = 17; };
72
73                 message Test {
74                   required string label = 1;
75                   optional int32 type = 2 [default=77];
76                   repeated int64 reps = 3;
77                   optional group OptionalGroup = 4 {
78                     required string RequiredField = 5;
79                   };
80                 }
81
82         The resulting file, test.pb.go, is:
83
84                 package example
85
86                 import "goprotobuf.googlecode.com/hg/proto"
87
88                 type FOO int32
89                 const (
90                         FOO_X = 17
91                 )
92                 var FOO_name = map[int32] string {
93                         17: "X",
94                 }
95                 var FOO_value = map[string] int32 {
96                         "X": 17,
97                 }
98                 func NewFOO(x int32) *FOO {
99                         e := FOO(x)
100                         return &e
101                 }
102                 func (x FOO) String() string {
103                         return proto.EnumName(FOO_name, int32(x))
104                 }
105
106                 type Test struct {
107                         Label   *string `protobuf:"bytes,1,req,name=label"`
108                         Type    *int32  `protobuf:"varint,2,opt,name=type,def=77"`
109                         Reps    []int64 `protobuf:"varint,3,rep,name=reps"`
110                         Optionalgroup   *Test_OptionalGroup     `protobuf:"group,4,opt,name=optionalgroup"`
111                         XXX_unrecognized []byte
112                 }
113                 func (this *Test) Reset() {
114                         *this = Test{}
115                 }
116                 const Default_Test_Type int32 = 77
117
118                 type Test_OptionalGroup struct {
119                         RequiredField   *string `protobuf:"bytes,5,req"`
120                         XXX_unrecognized []byte
121                 }
122                 func (this *Test_OptionalGroup) Reset() {
123                         *this = Test_OptionalGroup{}
124                 }
125
126                 func init() {
127                         proto.RegisterEnum("example.FOO", FOO_name, FOO_value)
128                 }
129
130         To create and play with a Test object:
131
132                 package main
133
134                 import (
135                         "log"
136
137                         "goprotobuf.googlecode.com/hg/proto"
138                         "./example.pb"
139                 )
140
141                 func main() {
142                         test := &example.Test{
143                                 Label: proto.String("hello"),
144                                 Type: proto.Int32(17),
145                                 Optionalgroup: &example.Test_OptionalGroup{
146                                         RequiredField: proto.String("good bye"),
147                                 },
148                         }
149                         data, err := proto.Marshal(test)
150                         if err != nil {
151                                 log.Fatal("marshaling error: ", err)
152                         }
153                         newTest := new(example.Test)
154                         err = proto.Unmarshal(data, newTest)
155                         if err != nil {
156                                 log.Fatal("unmarshaling error: ", err)
157                         }
158                         // Now test and newTest contain the same data.
159                         if proto.GetString(test.Label) != proto.GetString(newTest.Label) {
160                                 log.Fatalf("data mismatch %q != %q", proto.GetString(test.Label), proto.GetString(newTest.Label))
161                         }
162                         // etc.
163                 }
164 */
165 package proto
166
167 import (
168         "fmt"
169         "log"
170         "reflect"
171         "strconv"
172         "sync"
173 )
174
175 // Stats records allocation details about the protocol buffer encoders
176 // and decoders.  Useful for tuning the library itself.
177 type Stats struct {
178         Emalloc uint64 // mallocs in encode
179         Dmalloc uint64 // mallocs in decode
180         Encode  uint64 // number of encodes
181         Decode  uint64 // number of decodes
182         Chit    uint64 // number of cache hits
183         Cmiss   uint64 // number of cache misses
184 }
185
186 var stats Stats
187
188 // GetStats returns a copy of the global Stats structure.
189 func GetStats() Stats { return stats }
190
191 // A Buffer is a buffer manager for marshaling and unmarshaling
192 // protocol buffers.  It may be reused between invocations to
193 // reduce memory usage.  It is not necessary to use a Buffer;
194 // the global functions Marshal and Unmarshal create a
195 // temporary Buffer and are fine for most applications.
196 type Buffer struct {
197         buf       []byte     // encode/decode byte stream
198         index     int        // write point
199         freelist  [10][]byte // list of available buffers
200         nfreelist int        // number of free buffers
201         ptr       uintptr    // scratch area for pointers
202 }
203
204 // NewBuffer allocates a new Buffer and initializes its internal data to
205 // the contents of the argument slice.
206 func NewBuffer(e []byte) *Buffer {
207         p := new(Buffer)
208         if e == nil {
209                 e = p.bufalloc()
210         }
211         p.buf = e
212         p.index = 0
213         return p
214 }
215
216 // Reset resets the Buffer, ready for marshaling a new protocol buffer.
217 func (p *Buffer) Reset() {
218         if p.buf == nil {
219                 p.buf = p.bufalloc()
220         }
221         p.buf = p.buf[0:0] // for reading/writing
222         p.index = 0        // for reading
223 }
224
225 // SetBuf replaces the internal buffer with the slice,
226 // ready for unmarshaling the contents of the slice.
227 func (p *Buffer) SetBuf(s []byte) {
228         p.buf = s
229         p.index = 0
230 }
231
232 // Bytes returns the contents of the Buffer.
233 func (p *Buffer) Bytes() []byte { return p.buf }
234
235 // Allocate a buffer for the Buffer.
236 func (p *Buffer) bufalloc() []byte {
237         if p.nfreelist > 0 {
238                 // reuse an old one
239                 p.nfreelist--
240                 s := p.freelist[p.nfreelist]
241                 return s[0:0]
242         }
243         // make a new one
244         s := make([]byte, 0, 16)
245         return s
246 }
247
248 // Free (and remember in freelist) a byte buffer for the Buffer.
249 func (p *Buffer) buffree(s []byte) {
250         if p.nfreelist < len(p.freelist) {
251                 // Take next slot.
252                 p.freelist[p.nfreelist] = s
253                 p.nfreelist++
254                 return
255         }
256
257         // Find the smallest.
258         besti := -1
259         bestl := len(s)
260         for i, b := range p.freelist {
261                 if len(b) < bestl {
262                         besti = i
263                         bestl = len(b)
264                 }
265         }
266
267         // Overwrite the smallest.
268         if besti >= 0 {
269                 p.freelist[besti] = s
270         }
271 }
272
273 /*
274  * Helper routines for simplifying the creation of optional fields of basic type.
275  */
276
277 // Bool is a helper routine that allocates a new bool value
278 // to store v and returns a pointer to it.
279 func Bool(v bool) *bool {
280         p := new(bool)
281         *p = v
282         return p
283 }
284
285 // Int32 is a helper routine that allocates a new int32 value
286 // to store v and returns a pointer to it.
287 func Int32(v int32) *int32 {
288         p := new(int32)
289         *p = v
290         return p
291 }
292
293 // Int is a helper routine that allocates a new int32 value
294 // to store v and returns a pointer to it, but unlike Int32
295 // its argument value is an int.
296 func Int(v int) *int32 {
297         p := new(int32)
298         *p = int32(v)
299         return p
300 }
301
302 // Int64 is a helper routine that allocates a new int64 value
303 // to store v and returns a pointer to it.
304 func Int64(v int64) *int64 {
305         p := new(int64)
306         *p = v
307         return p
308 }
309
310 // Float32 is a helper routine that allocates a new float32 value
311 // to store v and returns a pointer to it.
312 func Float32(v float32) *float32 {
313         p := new(float32)
314         *p = v
315         return p
316 }
317
318 // Float64 is a helper routine that allocates a new float64 value
319 // to store v and returns a pointer to it.
320 func Float64(v float64) *float64 {
321         p := new(float64)
322         *p = v
323         return p
324 }
325
326 // Uint32 is a helper routine that allocates a new uint32 value
327 // to store v and returns a pointer to it.
328 func Uint32(v uint32) *uint32 {
329         p := new(uint32)
330         *p = v
331         return p
332 }
333
334 // Uint64 is a helper routine that allocates a new uint64 value
335 // to store v and returns a pointer to it.
336 func Uint64(v uint64) *uint64 {
337         p := new(uint64)
338         *p = v
339         return p
340 }
341
342 // String is a helper routine that allocates a new string value
343 // to store v and returns a pointer to it.
344 func String(v string) *string {
345         p := new(string)
346         *p = v
347         return p
348 }
349
350 /*
351  * Helper routines for simplifying the fetching of optional fields of basic type.
352  * If the field is missing, they return the zero for the type.
353  */
354
355 // GetBool is a helper routine that returns an optional bool value.
356 func GetBool(p *bool) bool {
357         if p == nil {
358                 return false
359         }
360         return *p
361 }
362
363 // GetInt32 is a helper routine that returns an optional int32 value.
364 func GetInt32(p *int32) int32 {
365         if p == nil {
366                 return 0
367         }
368         return *p
369 }
370
371 // GetInt64 is a helper routine that returns an optional int64 value.
372 func GetInt64(p *int64) int64 {
373         if p == nil {
374                 return 0
375         }
376         return *p
377 }
378
379 // GetFloat32 is a helper routine that returns an optional float32 value.
380 func GetFloat32(p *float32) float32 {
381         if p == nil {
382                 return 0
383         }
384         return *p
385 }
386
387 // GetFloat64 is a helper routine that returns an optional float64 value.
388 func GetFloat64(p *float64) float64 {
389         if p == nil {
390                 return 0
391         }
392         return *p
393 }
394
395 // GetUint32 is a helper routine that returns an optional uint32 value.
396 func GetUint32(p *uint32) uint32 {
397         if p == nil {
398                 return 0
399         }
400         return *p
401 }
402
403 // GetUint64 is a helper routine that returns an optional uint64 value.
404 func GetUint64(p *uint64) uint64 {
405         if p == nil {
406                 return 0
407         }
408         return *p
409 }
410
411 // GetString is a helper routine that returns an optional string value.
412 func GetString(p *string) string {
413         if p == nil {
414                 return ""
415         }
416         return *p
417 }
418
419 // EnumName is a helper function to simplify printing protocol buffer enums
420 // by name.  Given an enum map and a value, it returns a useful string.
421 func EnumName(m map[int32]string, v int32) string {
422         s, ok := m[v]
423         if ok {
424                 return s
425         }
426         return "unknown_enum_" + strconv.Itoa(int(v))
427 }
428
429 // DebugPrint dumps the encoded data in b in a debugging format with a header
430 // including the string s. Used in testing but made available for general debugging.
431 func (o *Buffer) DebugPrint(s string, b []byte) {
432         var u uint64
433
434         obuf := o.buf
435         index := o.index
436         o.buf = b
437         o.index = 0
438         depth := 0
439
440         fmt.Printf("\n--- %s ---\n", s)
441
442 out:
443         for {
444                 for i := 0; i < depth; i++ {
445                         fmt.Print("  ")
446                 }
447
448                 index := o.index
449                 if index == len(o.buf) {
450                         break
451                 }
452
453                 op, err := o.DecodeVarint()
454                 if err != nil {
455                         fmt.Printf("%3d: fetching op err %v\n", index, err)
456                         break out
457                 }
458                 tag := op >> 3
459                 wire := op & 7
460
461                 switch wire {
462                 default:
463                         fmt.Printf("%3d: t=%3d unknown wire=%d\n",
464                                 index, tag, wire)
465                         break out
466
467                 case WireBytes:
468                         var r []byte
469
470                         r, err = o.DecodeRawBytes(false)
471                         if err != nil {
472                                 break out
473                         }
474                         fmt.Printf("%3d: t=%3d bytes [%d]", index, tag, len(r))
475                         if len(r) <= 6 {
476                                 for i := 0; i < len(r); i++ {
477                                         fmt.Printf(" %.2x", r[i])
478                                 }
479                         } else {
480                                 for i := 0; i < 3; i++ {
481                                         fmt.Printf(" %.2x", r[i])
482                                 }
483                                 fmt.Printf(" ..")
484                                 for i := len(r) - 3; i < len(r); i++ {
485                                         fmt.Printf(" %.2x", r[i])
486                                 }
487                         }
488                         fmt.Printf("\n")
489
490                 case WireFixed32:
491                         u, err = o.DecodeFixed32()
492                         if err != nil {
493                                 fmt.Printf("%3d: t=%3d fix32 err %v\n", index, tag, err)
494                                 break out
495                         }
496                         fmt.Printf("%3d: t=%3d fix32 %d\n", index, tag, u)
497
498                 case WireFixed64:
499                         u, err = o.DecodeFixed64()
500                         if err != nil {
501                                 fmt.Printf("%3d: t=%3d fix64 err %v\n", index, tag, err)
502                                 break out
503                         }
504                         fmt.Printf("%3d: t=%3d fix64 %d\n", index, tag, u)
505                         break
506
507                 case WireVarint:
508                         u, err = o.DecodeVarint()
509                         if err != nil {
510                                 fmt.Printf("%3d: t=%3d varint err %v\n", index, tag, err)
511                                 break out
512                         }
513                         fmt.Printf("%3d: t=%3d varint %d\n", index, tag, u)
514
515                 case WireStartGroup:
516                         if err != nil {
517                                 fmt.Printf("%3d: t=%3d start err %v\n", index, tag, err)
518                                 break out
519                         }
520                         fmt.Printf("%3d: t=%3d start\n", index, tag)
521                         depth++
522
523                 case WireEndGroup:
524                         depth--
525                         if err != nil {
526                                 fmt.Printf("%3d: t=%3d end err %v\n", index, tag, err)
527                                 break out
528                         }
529                         fmt.Printf("%3d: t=%3d end\n", index, tag)
530                 }
531         }
532
533         if depth != 0 {
534                 fmt.Printf("%3d: start-end not balanced %d\n", o.index, depth)
535         }
536         fmt.Printf("\n")
537
538         o.buf = obuf
539         o.index = index
540 }
541
542 // SetDefaults sets unset protocol buffer fields to their default values.
543 // It only modifies fields that are both unset and have defined defaults.
544 // It recursively sets default values in any non-nil sub-messages.
545 func SetDefaults(pb interface{}) {
546         v := reflect.ValueOf(pb)
547         if v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct {
548                 log.Printf("proto: hit non-pointer-to-struct %v", v)
549         }
550         setDefaults(v, true, false)
551 }
552
553 // v is a pointer to a struct.
554 func setDefaults(v reflect.Value, recur, zeros bool) {
555         v = v.Elem()
556
557         defaultMu.Lock()
558         dm, ok := defaults[v.Type()]
559         defaultMu.Unlock()
560         if !ok {
561                 dm = buildDefaultMessage(v.Type())
562                 defaultMu.Lock()
563                 defaults[v.Type()] = dm
564                 defaultMu.Unlock()
565         }
566
567         for _, sf := range dm.scalars {
568                 f := v.Field(sf.index)
569                 if !f.IsNil() {
570                         // field already set
571                         continue
572                 }
573                 dv := sf.value
574                 if dv == nil && !zeros {
575                         // no explicit default, and don't want to set zeros
576                         continue
577                 }
578                 fptr := f.Addr().Interface() // **T
579                 // TODO: Consider batching the allocations we do here.
580                 switch sf.kind {
581                 case reflect.Bool:
582                         b := new(bool)
583                         if dv != nil {
584                                 *b = dv.(bool)
585                         }
586                         *(fptr.(**bool)) = b
587                 case reflect.Float32:
588                         f := new(float32)
589                         if dv != nil {
590                                 *f = dv.(float32)
591                         }
592                         *(fptr.(**float32)) = f
593                 case reflect.Float64:
594                         f := new(float64)
595                         if dv != nil {
596                                 *f = dv.(float64)
597                         }
598                         *(fptr.(**float64)) = f
599                 case reflect.Int32:
600                         // might be an enum
601                         if ft := f.Type(); ft != int32PtrType {
602                                 // enum
603                                 f.Set(reflect.New(ft.Elem()))
604                                 if dv != nil {
605                                         f.Elem().SetInt(int64(dv.(int32)))
606                                 }
607                         } else {
608                                 // int32 field
609                                 i := new(int32)
610                                 if dv != nil {
611                                         *i = dv.(int32)
612                                 }
613                                 *(fptr.(**int32)) = i
614                         }
615                 case reflect.Int64:
616                         i := new(int64)
617                         if dv != nil {
618                                 *i = dv.(int64)
619                         }
620                         *(fptr.(**int64)) = i
621                 case reflect.String:
622                         s := new(string)
623                         if dv != nil {
624                                 *s = dv.(string)
625                         }
626                         *(fptr.(**string)) = s
627                 case reflect.Uint8:
628                         // exceptional case: []byte
629                         var b []byte
630                         if dv != nil {
631                                 db := dv.([]byte)
632                                 b = make([]byte, len(db))
633                                 copy(b, db)
634                         } else {
635                                 b = []byte{}
636                         }
637                         *(fptr.(*[]byte)) = b
638                 case reflect.Uint32:
639                         u := new(uint32)
640                         if dv != nil {
641                                 *u = dv.(uint32)
642                         }
643                         *(fptr.(**uint32)) = u
644                 case reflect.Uint64:
645                         u := new(uint64)
646                         if dv != nil {
647                                 *u = dv.(uint64)
648                         }
649                         *(fptr.(**uint64)) = u
650                 default:
651                         log.Printf("proto: can't set default for field %v (sf.kind=%v)", f, sf.kind)
652                 }
653         }
654
655         for _, ni := range dm.nested {
656                 setDefaults(v.Field(ni), recur, zeros)
657         }
658 }
659
660 var (
661         // defaults maps a protocol buffer struct type to a slice of the fields,
662         // with its scalar fields set to their proto-declared non-zero default values.
663         defaultMu sync.Mutex
664         defaults  = make(map[reflect.Type]defaultMessage)
665
666         int32PtrType = reflect.TypeOf((*int32)(nil))
667 )
668
669 // defaultMessage represents information about the default values of a message.
670 type defaultMessage struct {
671         scalars []scalarField
672         nested  []int // struct field index of nested messages
673 }
674
675 type scalarField struct {
676         index int          // struct field index
677         kind  reflect.Kind // element type (the T in *T or []T)
678         value interface{}  // the proto-declared default value, or nil
679 }
680
681 // t is a struct type.
682 func buildDefaultMessage(t reflect.Type) (dm defaultMessage) {
683         sprop := GetProperties(t)
684         for _, prop := range sprop.Prop {
685                 fi := sprop.tags[prop.Tag]
686                 ft := t.Field(fi).Type
687
688                 // nested messages
689                 if ft.Kind() == reflect.Ptr && ft.Elem().Kind() == reflect.Struct {
690                         dm.nested = append(dm.nested, fi)
691                         continue
692                 }
693
694                 sf := scalarField{
695                         index: fi,
696                         kind:  ft.Elem().Kind(),
697                 }
698
699                 // scalar fields without defaults
700                 if prop.Default == "" {
701                         dm.scalars = append(dm.scalars, sf)
702                         continue
703                 }
704
705                 // a scalar field: either *T or []byte
706                 switch ft.Elem().Kind() {
707                 case reflect.Bool:
708                         x, err := strconv.Atob(prop.Default)
709                         if err != nil {
710                                 log.Printf("proto: bad default bool %q: %v", prop.Default, err)
711                                 continue
712                         }
713                         sf.value = x
714                 case reflect.Float32:
715                         x, err := strconv.Atof32(prop.Default)
716                         if err != nil {
717                                 log.Printf("proto: bad default float32 %q: %v", prop.Default, err)
718                                 continue
719                         }
720                         sf.value = x
721                 case reflect.Float64:
722                         x, err := strconv.Atof64(prop.Default)
723                         if err != nil {
724                                 log.Printf("proto: bad default float64 %q: %v", prop.Default, err)
725                                 continue
726                         }
727                         sf.value = x
728                 case reflect.Int32:
729                         x, err := strconv.Atoi64(prop.Default)
730                         if err != nil {
731                                 log.Printf("proto: bad default int32 %q: %v", prop.Default, err)
732                                 continue
733                         }
734                         sf.value = int32(x)
735                 case reflect.Int64:
736                         x, err := strconv.Atoi64(prop.Default)
737                         if err != nil {
738                                 log.Printf("proto: bad default int64 %q: %v", prop.Default, err)
739                                 continue
740                         }
741                         sf.value = x
742                 case reflect.String:
743                         sf.value = prop.Default
744                 case reflect.Uint8:
745                         // []byte (not *uint8)
746                         sf.value = []byte(prop.Default)
747                 case reflect.Uint32:
748                         x, err := strconv.Atoui64(prop.Default)
749                         if err != nil {
750                                 log.Printf("proto: bad default uint32 %q: %v", prop.Default, err)
751                                 continue
752                         }
753                         sf.value = uint32(x)
754                 case reflect.Uint64:
755                         x, err := strconv.Atoui64(prop.Default)
756                         if err != nil {
757                                 log.Printf("proto: bad default uint64 %q: %v", prop.Default, err)
758                                 continue
759                         }
760                         sf.value = x
761                 default:
762                         log.Printf("proto: unhandled def kind %v", ft.Elem().Kind())
763                         continue
764                 }
765
766                 dm.scalars = append(dm.scalars, sf)
767         }
768
769         return dm
770 }